YaqeenDocs
Back to Yaqeen

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:

json
{ "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:

json
{
  "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:

HeaderValue
X-Yaqeen-Event-IdThe event id. It is the same on every retry.
X-Yaqeen-EventThe event type, such as hold.approved.
X-Yaqeen-TimestampThe send time as Unix seconds.
X-Yaqeen-SignatureThe 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.

python
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 with status and event_type. Each row has created_at and status (pending, delivered or failed), attempts, last_status_code and last_error. last_error is empty after a success, http_<code> when your server answered with another status, or one of timeout, refused, tls, dns, blocked_address (the host pointed inside a private network) and network.
  • GET /api/v1/webhooks/deliveries/{delivery_id}/ returns one delivery with the body that 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_url when you add an address: the address is not https, 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. Check last_status_code and last_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#

Up Down to moveEnter to openEsc to close