Subscribes a URL to one webhook event. Payment Labs then posts every occurrence of that event to the URL.
Requires the payout Administrator role.
Rules:
- One registration covers one event. To receive several events, call Add Webhook once per event; they can share a URL.
- Registering the same
eventanddestinationagain does nothing and returns204. - The response has no body. Call List Webhooks to get the
webhookIdand thehmacKeyof the new registration. - There is no update. To change a URL, add the new registration, then delete the old one with Delete Webhook.
Each delivery is a POST to destination with a JSON body {"payorId", "event", "timestamp", "data"} and these headers:
x-signature: hex-encoded HMAC-SHA512 ofdata, serialized as JSON, keyed with the registration'shmacKey. Verify it before
you trust the request.x-environment: the Payment Labs environment that sent the event.
Answer with a 2xx status. Payment Labs retries a failed delivery once, a few seconds later, then records it as failed
in List Webhook Logs; use Resend Webhook to deliver it again. Deliveries can arrive out of order or more than once, and data
holds the entity as it is when the event is sent, so two deliveries can carry the same state. Make your handler idempotent:
compare the entity's ID and status with what you already processed.
See Webhook Events for the data of each event.
Errors
400 VALIDATION_ERROR:eventordestinationis missing,eventis not an event name Payment Labs knows, or the body has
a field not listed here. Some event names that are not listed are also accepted; register only the listed values.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
204The operation succeeded. The response has no body.
