How-to guide
Webhooks
Receive a signed event when a hold or an appeal changes, and check each call.
This guide shows how to add a webhook endpoint, check the signature on each call, and handle repeats. A webhook is a call that Yaqeen sends to your server when something changes. Only an admin can manage webhooks. An API key cannot.
Add an endpoint#
Send POST /api/v1/webhooks/ as an admin:
{ "url": "https://hooks.example.test/yaqeen", "events": ["hold.approved", "hold.released", "appeal.decided"] }The response has the endpoint id and a secret that starts with whsec_. The secret is shown once. Save it now.
The rules for the address and the list:
- The address must start with
https://. Yaqeen resolves the host name when you add it. It refuses a host that does not exist or that points inside a private network. - You can have 5 active endpoints. The sixth gets
409 too_many. - Choose events from the list in Webhook events.
An admin can also add an endpoint in the dashboard under Settings, Webhooks. The screen lists each address with a status: healthy, failing (the newest event is not delivered and has been tried) or idle (nothing sent yet).
GET /api/v1/webhooks/events/ lists the event types with a sentence in English and Arabic and an example body. ping has "subscribe": false, because you start it yourself.
Change an endpoint#
Send PATCH /api/v1/webhooks/{id}/ with a new url, a new events list, or both. The secret stays the same. The new address is checked like a new one, and a change is written to the audit log without the address. The answer is the endpoint, or 400 bad_events and 400 bad_url.
Send a test event#
Send POST /api/v1/webhooks/{id}/ping/. The answer is 202 with the queued delivery. Your server then receives an event of type ping with an empty data object.
What you receive#
Each call is a POST with a JSON body:
{
"id": "7d0c4b1e-2f6a-4c53-9b1e-0a1d2c3b4e5f",
"type": "hold.approved",
"created": "2026-11-14T12:00:00.000000+00:00",
"data": { "hold_id": "e1b2c3d4-0000-4000-8000-000000000001", "kind": "hold_approved" }
}The payload carries ids and the new status only. It has no amount, no name and no reason. Fetch the rest with the API.
These headers come with every call:
| Header | Value |
|---|---|
X-Yaqeen-Event-Id | The event id. It is the same on every retry. |
X-Yaqeen-Event | The event type, such as hold.approved. |
X-Yaqeen-Timestamp | The send time as Unix seconds. |
X-Yaqeen-Signature | The signature, as a hex string. |
Rotate the secret#
Send POST /api/v1/webhooks/{id}/rotate-secret/. The answer has the new secret, shown once. For the next 24 hours each call carries two signatures: X-Yaqeen-Signature made with the new secret and X-Yaqeen-Signature-Previous made with the old one. Switch your receiver to the new secret in that time. Accept a call when either signature is valid until you have switched. After 24 hours only the new secret signs.
Check every call#
The signature is the HMAC-SHA256 of the timestamp, a dot, and the raw body. The key is your endpoint secret. Check the signature on the exact bytes you received, before you parse the JSON. Reject a timestamp more than 5 minutes from your clock.
import hashlib, hmac, time
def valid(secret, timestamp, body, signature):
if abs(time.time() - int(timestamp)) > 300:
return False
expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)Handle repeats#
Delivery is at least once. The same event can reach you more than once. Store each event id you have handled and ignore an id you have seen.
Answer with any 2xx status within 5 seconds. Yaqeen counts every other answer, and a timeout, as a failure. That includes a redirect (3xx): Yaqeen does not follow it, so give the final address when you add the endpoint.
Before each call Yaqeen looks the host up again and sends only to a public address. If the name now points inside a private network, the call is not made.
Retries#
After a failure Yaqeen tries again after 1, 5, 30, 120, 360 and 720 minutes. That is 7 attempts over about 20 hours. After the last failure the delivery is marked failed and Yaqeen sends an alert, if the operator has set up an alert channel.
Events are sent in batches about every 5 minutes, so an event can arrive a few minutes after the change.
Look at deliveries and send one again#
GET /api/v1/webhooks/{id}/deliveries/lists the attempts for one endpoint, newest first. Filter withstatusandevent_type. Each row hascreated_atandstatus(pending,deliveredorfailed),attempts,last_status_codeandlast_error.last_erroris empty after a success,http_<code>when your server answered with another status, or one oftimeout,refused,tls,dns,blocked_address(the host pointed inside a private network) andnetwork.GET /api/v1/webhooks/deliveries/{delivery_id}/returns one delivery with thebodythat was sent.POST /api/v1/webhooks/deliveries/{delivery_id}/replay/queues the same event again with the same event id. Use it after you fix your server.DELETE /api/v1/webhooks/{id}/removes an endpoint. It stops receiving events.
If it does not work#
- You get
400 bad_urlwhen you add an address: the address is nothttps, the host was not found, or it is inside a private network. - Deliveries stay
pending: your server answered with an error, and Yaqeen is waiting for the next retry. Checklast_status_codeandlast_error. - Your signature check fails: check that you use the raw body and the secret of this endpoint. A parsed and re-written body has different bytes.
Next steps#
- Webhook events: when each event fires and what it carries.
- Go live checklist: test your endpoint before you load real data.