Reference
Webhook events
The event types Yaqeen sends to a webhook endpoint, when each one fires, and what it carries.
This page lists the four event types that a webhook endpoint can subscribe to. To subscribe, see Webhooks.
The envelope#
Every event has the same outer shape.
| Field | Type | Meaning |
|---|---|---|
id | string (UUID) | The event id. It stays the same on every retry and replay. |
type | string | One of the event types below. |
created | string | The time Yaqeen queued the event, in ISO 8601 with a UTC offset. |
data | object | The fields for this event type. |
Each call also has the headers X-Yaqeen-Event-Id, X-Yaqeen-Event, X-Yaqeen-Timestamp and X-Yaqeen-Signature. A payload never has an amount, a name or a reason. See Webhooks for how to check the signature.
hold.approved#
A reviewer approved a hold, and the payout is now held. This also fires when a second person approves a change that was waiting.
Field in data | Value |
|---|---|
hold_id | The id of the hold. |
kind | hold_approved |
{ "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" } }hold.released#
A held payout was released. This fires in two cases: a reviewer or admin released the hold, or Yaqeen released it automatically after the hold_until date passed with no open appeal.
Field in data | Value |
|---|---|
hold_id | The id of the hold. |
kind | hold_released |
appeal.decided#
A reviewer accepted or rejected an appeal. One event type covers both results. Read kind to tell them apart.
Field in data | Value |
|---|---|
hold_id | The id of the hold that was appealed. |
kind | appeal_accepted or appeal_rejected |
When a reviewer accepts an appeal, Yaqeen releases the hold too. That release sends appeal.decided only. It does not send a separate hold.released.
ping#
A test event. It fires when an admin sends POST /api/v1/webhooks/{id}/ping/. The data object is empty.
{ "id": "0b4e7a52-8c1d-4f60-a3b2-6d9e1f2a3b4c", "type": "ping", "created": "2026-11-14T12:05:00.000000+00:00", "data": {} }What does not send an event#
- A hold that is only recommended, and a recommendation that a reviewer rejects. The merchant never sees these.
- Changes to cases, reserves, disputes, applications and policies.
Delivery rules#
| Rule | Value |
|---|---|
| Method | POST with a JSON body |
| Success | Any 2xx answer within 5 seconds |
| Retries | After 1, 5, 30, 120, 360 and 720 minutes, so 7 attempts in all |
| After the last failure | The delivery status becomes failed |
| Delivery statuses | pending, delivered, failed |
| Endpoints per organization | 5 active |
Related#
- Webhooks: add an endpoint and check the signature.
- Hold statuses: the status changes behind each event.