Webhooks

Overview

Webhooks let you receive real-time HTTP notifications when events occur in your Bluejay simulations, observability logs, and alerts. Instead of polling, Bluejay sends a POST request to your endpoint whenever a subscribed event fires. See the Events Webhook reference for the full payload schema.

Security

Source

All webhook requests originate from api.getbluejay.ai. If your endpoint sits behind a firewall or IP allowlist, whitelist that hostname (or its resolved IPs) so our requests can reach you.

Request headers

Every webhook request includes the following headers:

Header	Description
`Content-Type`	Always `application/json`.
`User-Agent`	Identifies the request as coming from Bluejay.
`X-Bluejay-Signature`	HMAC-SHA256 signature of the raw request body, signed with your webhook’s signing secret. Use this to verify the request came from Bluejay.
`X-Bluejay-Event`	The event type (for example, `simulation_result_evaluated`). Matches the `type` field in the body.
`X-Bluejay-Delivery`	Unique ID for this delivery attempt. Useful for idempotency and log correlation.

Verifying requests

Read the raw request body (do not re-serialize the JSON — signature verification is byte-sensitive).
Compute HMAC-SHA256(body, signing_secret) using the signing secret shown in your webhook settings.
Compare the hex digest against the X-Bluejay-Signature header using a constant-time comparison.

Reject any request whose signature does not match.

Recommendations

Always use an HTTPS endpoint.
Respond within 5 seconds; do heavier work asynchronously.
Treat deliveries as at-least-once and dedupe on X-Bluejay-Delivery.

Events

You can subscribe to these event types. Select a tab to see its payload.

Fires when a simulation result finishes evaluating.Event type: simulation_result_evaluated

{
  "type": "simulation_result_evaluated",
  "id": 123,
  "digital_human_id": 456,
  "status": "COMPLETED",
  "simulation_run_id": 789,
  "simulation_id": 12,
  "agent_id": 34,
  "folder_id": "d3b1e0f0-1234-5678-9abc-def012345678",
  "evaluations": [ ... ],
  "events": [ ... ],
  "tool_calls": [ ... ],
  "tags": [],
  "metadata": {},
  "created_at": "2026-07-16T18:00:00Z",
  "start_time": "2026-07-16T18:00:05Z",
  "end_time": "2026-07-16T18:02:10Z",
  "duration": 125
}

Fires when an observability call finishes evaluating. The payload is the full call log with the event type attached.Event type: observability_call_evaluated

{
  "type": "observability_call_evaluated",
  "id": "call_123",
  "agent_id": 34,
  "evaluations": [ ... ],
  "transcript": [ ... ],
  "metadata": {}
}

Fires when a simulation instance completes execution, before evaluation runs.Event type: simulation_ended

{
  "type": "simulation_ended",
  "id": 123,
  "digital_human_id": 456,
  "status": "CONVERSATION_ENDED",
  "simulation_run_id": 789,
  "created_at": "2026-07-16T18:00:00Z",
  "start_time": "2026-07-16T18:00:05Z",
  "end_time": "2026-07-16T18:02:10Z",
  "duration": 125
}

Fires when an outbound simulation kicks off.Event type: outbound_simulation_started

{
  "type": "outbound_simulation_started",
  "agent_id": 34,
  "simulation_id": 12,
  "simulation_run_id": 789,
  "digital_humans": [
    {
      "id": 456,
      "name": "Maria Gonzalez",
      "phone_number": "+15551234567",
      "associated_simulation_result_ids": [123]
    }
  ]
}

Fires when an observability alert enters or leaves alarm. Subscribe under Settings → Webhooks — not on the alert itself.Event type: observability_alert_triggered

{
  "type": "observability_alert_triggered",
  "subtype": "triggered",
  "alert_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "alert_name": "High latency",
  "display_text": "Threshold: 5 events in 10 min",
  "organization_id": "org_123",
  "agent_id": 34,
  "event_count": 6,
  "min_events": 5
}

Fires when a simulation alert fires for a run. Subscribe under Settings → Webhooks — not on the alert itself.Event type: simulation_alert_triggered

{
  "type": "simulation_alert_triggered",
  "subtype": "triggered",
  "alert_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "alert_name": "Goal completion drop",
  "display_text": "Goal completion: avg across simulation run 789 was 0.4 (less_than 0.8)",
  "organization_id": "org_123",
  "agent_id": 34,
  "simulation_id": 12,
  "simulation_run_id": 789,
  "actual_value": 0.4,
  "operator": "less_than",
  "comparison_value": "0.8"
}

Scoping webhooks to agents and folders

When you create a webhook, pick the agents or folders it should listen to. Only events from those agents — or from any agent in the selected folders — will trigger delivery.

Select agents to narrow down to specific agents.
Select folders to include every agent in that folder.
Combine both for granular rules.

Troubleshooting

Webhook not triggering

Confirm the webhook is enabled.
Confirm the source agent or folder is in the webhook’s scope.
Confirm the event type is included in the subscription.
Confirm the endpoint URL is reachable and responds within 5 seconds.

Getting Started

Key Concepts

Test

Monitor

Integrations

Administration

Overview

Security

Source

Request headers

Verifying requests

Recommendations

Events

Scoping webhooks to agents and folders

Troubleshooting

​Overview

​Security

​Source

​Request headers

​Verifying requests

​Recommendations

​Events

​Scoping webhooks to agents and folders

​Troubleshooting

Overview

Security

Source

Request headers

Verifying requests

Recommendations

Events

Scoping webhooks to agents and folders

Troubleshooting