Add Webhook

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 event and destination again does nothing and returns 204.
  • The response has no body. Call List Webhooks to get the webhookId and the hmacKey of 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 of data, serialized as JSON, keyed with the registration's hmacKey. 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: event or destination is missing, event is 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.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
enum
required

Event to subscribe to.

string
required

HTTPS URL that receives the event. It must accept POST requests with a JSON body. Payment Labs does not check the URL when
you register it, so test it with a real event.

Responses
204

The operation succeeded. The response has no body.

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json