YaqeenDocs
Back to Yaqeen

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.

FieldTypeMeaning
idstring (UUID)The event id. It stays the same on every retry and replay.
typestringOne of the event types below.
createdstringThe time Yaqeen queued the event, in ISO 8601 with a UTC offset.
dataobjectThe 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 dataValue
hold_idThe id of the hold.
kindhold_approved
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" } }

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 dataValue
hold_idThe id of the hold.
kindhold_released

appeal.decided#

A reviewer accepted or rejected an appeal. One event type covers both results. Read kind to tell them apart.

Field in dataValue
hold_idThe id of the hold that was appealed.
kindappeal_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.

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

RuleValue
MethodPOST with a JSON body
SuccessAny 2xx answer within 5 seconds
RetriesAfter 1, 5, 30, 120, 360 and 720 minutes, so 7 attempts in all
After the last failureThe delivery status becomes failed
Delivery statusespending, delivered, failed
Endpoints per organization5 active

Up Down to moveEnter to openEsc to close