Skip to main content

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​

  1. Open Settings, select Integrations, then Webhooks.
  2. Select New webhook.
  3. Enter a Name, such as CI bridge, and optionally a Description.
  4. Enter the URL Jaah posts to. It must start with https:// and point at a public address.
  5. Under Events, tick each event to send, such as Task done and Pull request merged. Every type is described in the event catalog.
  6. Under Projects, keep All projects, or clear it and tick the projects whose events to send.
  7. 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.1 or 169.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:

HeaderValue
X-Jaah-EventThe event type, such as task.done.
X-Jaah-DeliveryThe delivery's id. A redelivery keeps it, so use it to ignore a delivery you already handled.
X-Jaah-TimestampWhen this attempt was sent, in Unix seconds.
X-Jaah-Signaturesha256= 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:

  1. Read the raw request body, before any JSON parsing.
  2. Reject the request when X-Jaah-Timestamp is more than five minutes from your clock. This stops an old delivery being replayed.
  3. Compute sha256= + hex HMAC-SHA256 of <X-Jaah-Timestamp>.<raw body>, keyed with the secret.
  4. 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​

  1. Open the endpoint and select Secret.
  2. Select Rotate, then confirm.
  3. Copy the new secret: Jaah shows it once.
  4. 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.