Webhooks

Bluejay sends a signed POST request with a JSON body to your URL when it evaluates a conversation, ends a simulation, or fires an alert. The Events Webhook reference has the payload schemas.

Create a webhook

To create a webhook, open Settings → Webhooks in the workspace whose agents it should watch, and enter an HTTPS URL. A webhook fires only for agents in its own workspace. Copy the signing key to your receiver, which uses it to verify the signature of each request. To limit the webhook to some agents, select the agents or folders. A folder includes every agent in it. If you select no agents and no folders, the webhook fires for all agents in the workspace.

Events

UI label	`type` in the body	Fires when
Simulation evaluated		A simulation result finishes evaluation.
Simulation ended		A simulated conversation ends, before evaluation.
Outbound simulation started		An outbound simulation run starts.
Observability log evaluated		A production conversation finishes evaluation.
Observability alert triggered		An observability alert enters or leaves alarm.
Simulation alert triggered		A simulation alert fires or recovers for a run. `subtype` is `triggered` or `recovered`.

Verify the signature

Each request has an X-Bluejay-Signature header. The value is the hex HMAC-SHA256 of the raw body, signed with your webhook’s signing key.

Read the raw request body. Do not parse and serialize the JSON again, because the signature uses the exact bytes.
Compute HMAC-SHA256(body, signing_key) as a hex digest.
Compare it to X-Bluejay-Signature with a constant-time comparison.
If the values do not match, reject the request.

import hmac, hashlib

def is_valid(body: bytes, signature: str, signing_key: str) -> bool:
    expected = hmac.new(signing_key.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Delivery

Requests come from api.getbluejay.ai. If you use an allowlist, allow that host.
Bluejay sends each event once and does not retry.

Troubleshooting

If a webhook does not fire, do these checks:

Make sure the webhook is enabled.
Make sure the event is selected.
Make sure the agent is in the selected agents or folders.
Make sure the agent and the webhook are in the same workspace.
Check the tag. If a POST /v1/evaluate request sets webhook_tag, only webhooks with that tag fire. If it does not, webhooks that have a tag do not fire.
Make sure your URL is reachable from the internet.

Overview

Test

Monitor

Improve

Configure

Create a webhook

Events

Verify the signature

Delivery

Troubleshooting

​Create a webhook

​Events

​Verify the signature

​Delivery

​Troubleshooting

​Related

Create a webhook

Events

Verify the signature

Delivery

Troubleshooting

Related