Receive events with webhooks
Jaah sends each event you choose to your URL as a signed POST. This guide sets up an endpoint, checks
that your receiver verifies it, and shows what to do when deliveries fail.
You need to be an Owner or Admin of your organization, on a plan that includes webhooks.
Create an endpoint
- Open Settings, select Integrations, then Webhooks.
- Select New webhook.
- Enter a Name, such as
CI bridge, and optionally a Description. - Enter the URL Jaah posts to. It must start with
https://and point at a public address. - Under Events, tick each event to send, such as Task done and Pull request merged. Every type is described in the event catalog.
- Under Projects, keep All projects, or clear it and tick the projects whose events to send.
- Select Create.
Jaah shows the endpoint's signing secret once. Copy it into your receiver's configuration now: Jaah never shows it again. If you lose it, rotate it.
A new endpoint receives what happens from now on, not earlier events.
URLs Jaah refuses
Jaah refuses a URL, and saves nothing, when it:
- does not start with
https://; - resolves to a private, local, link-local or cloud metadata address, such as
10.0.0.5,127.0.0.1or169.254.169.254; - carries a user name and password, such as
https://user:pass@example.com.
The reason appears under the URL field. Jaah checks the address again before each delivery.
What a delivery looks like
Each delivery is an HTTPS POST with a JSON body and these headers:
| Header | Value |
|---|---|
X-Jaah-Event | The event type, such as task.done. |
X-Jaah-Delivery | The delivery's id. A redelivery keeps it, so use it to ignore a delivery you already handled. |
X-Jaah-Timestamp | When this attempt was sent, in Unix seconds. |
X-Jaah-Signature | sha256= and the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the secret. |
The body:
{
"id": "0193b7e2-5c1a-7c2e-9f1e-2a4b6c8d0e1f",
"type": "task.done",
"created_at": "2026-11-10T09:30:00+00:00",
"org": { "id": "…", "slug": "acme" },
"project": { "id": 12, "name": "shop" },
"data": {
"task": { "id": 4821, "title": "Fix checkout rounding", "state": "done", "url": "https://app.jaah.ai/tasks/4821" }
}
}
A pull request event's data also has pull_request with its url, number and, once merged,
merge_sha. The body carries ids, titles and links only: never a task's description or transcript.
A test ping names no task: its project is null and its data holds the endpoint you tested.
{
"id": "0193b7e4-1d2f-7a3b-8c4d-5e6f7a8b9c0d",
"type": "ping",
"created_at": "2026-11-10T09:31:00+00:00",
"org": { "id": "…", "slug": "acme" },
"project": null,
"data": {
"endpoint": { "id": "0193b7e0-9a8b-7c6d-8e5f-4a3b2c1d0e9f", "slug": "ci-alerts" }
}
}
Verify the signature
Verify every delivery before you act on it:
- Read the raw request body, before any JSON parsing.
- Reject the request when
X-Jaah-Timestampis more than five minutes from your clock. This stops an old delivery being replayed. - Compute
sha256=+ hex HMAC-SHA256 of<X-Jaah-Timestamp>.<raw body>, keyed with the secret. - Accept the request when it equals one of the comma-separated values in
X-Jaah-Signature. Compare in constant time.
X-Jaah-Signature holds two values for 24 hours after you rotate the secret, one per secret, so a receiver
that still has the old secret keeps accepting deliveries.
Python:
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 300
def verify(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
"""True when the delivery is Jaah's and fresh. `raw_body` is the body's bytes, exactly as received."""
if not signature:
return False
try:
sent = int(timestamp)
except (TypeError, ValueError):
return False
if abs(time.time() - sent) > TOLERANCE_SECONDS:
return False
signed = timestamp.encode() + b"." + raw_body
expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, value.strip()) for value in signature.split(","))
Node.js:
const crypto = require('node:crypto')
const TOLERANCE_SECONDS = 300
/** True when the delivery is Jaah's and fresh. `rawBody` is the body's Buffer, exactly as received. */
function verify(secret, timestamp, signature, rawBody) {
const sent = Number(timestamp)
if (!Number.isInteger(sent) || Math.abs(Date.now() / 1000 - sent) > TOLERANCE_SECONDS) return false
if (typeof signature !== 'string') return false
const expected = Buffer.from(
'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex'),
)
return signature.split(',').some(value => {
const given = Buffer.from(value.trim())
return given.length === expected.length && crypto.timingSafeEqual(given, expected)
})
}
Call it with the X-Jaah-Timestamp and X-Jaah-Signature headers and the raw body. In Express, read the
body with express.raw({ type: 'application/json' }), not express.json(): a re-serialized body no longer
matches its signature.
To check your receiver, open the endpoint and select Send test. Jaah sends a ping event at once and
the Deliveries tab shows what your receiver answered.
Answer and retries
Answer with any 2xx status within 10 seconds; Jaah does not follow redirects. Anything else, or no answer,
is a failed attempt. Jaah tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours.
After the seventh failed attempt the delivery is Failed and Jaah stops trying it. A test ping is not
retried.
A delivery can arrive more than once, and deliveries can arrive out of order: use X-Jaah-Delivery to skip
one you already handled, and created_at to order them.
Read the delivery log
Open the endpoint and select Deliveries. Each row is one delivery, newest first, with its event, its status, your receiver's last status code, how long it took to answer and how many attempts it took. Hover a status to read why the last attempt failed, or when the next one is due. The log keeps 30 days.
Redeliver
When a delivery failed, fix your receiver, then select Redeliver on its row. Jaah sends it again at once,
with the same body and X-Jaah-Delivery, a new timestamp and signature, and a fresh round of retries. The row
then shows the new result.
Rotate the secret
- Open the endpoint and select Secret.
- Select Rotate, then confirm.
- Copy the new secret: Jaah shows it once.
- Put the new secret in your receiver within 24 hours. Until then each delivery is signed with both secrets.
Change, disable or delete an endpoint
- To change the URL, events or projects, edit them on Settings and select Save.
- To pause deliveries, clear Enabled and save. Events while it is off are not sent later: when you enable it again, it sends what happens from then on.
- To delete it, select ⋯ > Delete and confirm. Its delivery log is deleted too.
Manage webhooks through the API
Every step above is also a call to the Jaah API: see the Webhooks endpoints in the API reference.