Webhook payload

Overview

Calypso sends webhook requests to the merchant endpoint in JSON format.

Each webhook contains a common envelope and an event-specific data object. The fields inside data depend on the webhook event type.

Payload example

{
  "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
  "id": 1,
  "createdDate": "2022-03-15T12:13:05.909616",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_CREATE_INVOICE",
  "data": {
    "parentExternalId": "3",
    "amount": 0.01,
    "currency": "ETH",
    "fiatCurrency": "USD",
    "message": "Invoice example",
    "createdDate": "2022-03-15T12:13:03.157015",
    "type": "INVOICE_CREATE_INVOICE",
    "idempotencyKey": "5b0ca8da-6af4-4a1c-9efd-5cbfc19ace09"
  }
}

Common payload fields

Field	Type	Required	Description
requestId	string	Yes	ID of the webhook subscription request.
id	number	Yes	Event ID.
createdDate	string	Yes	Date and time when the event was created.
level	string	Yes	Notification level, for example SUCCESS, INFO, or WARNING.
service	string	Yes	Event group, for example INVOICE, PAYOUT, or WALLET.
eventType	string	Yes	Specific webhook event type.
data	object	Yes	Event-specific payload.

Subscription filters

There are two ways to select which webhooks should be sent to the merchant endpoint.

Field	Description
notificationServiceTypes	Event groups. Use this field to subscribe to all events in selected groups, for example INVOICE, PAYOUT, or WALLET.
notificationEventTypes	Specific event types. Use this field to subscribe only to selected events.

Both fields can be used together.

Recommended handling

Case	Recommendation
Event-specific fields are needed	Use eventType to select the correct parser for the data object.
Unknown field is received	Ignore unknown fields and continue processing the webhook.
Current object status is required	Request the object through the relevant API method after receiving the webhook.

Related docs

Document	Link
Delivery order	Delivery order
Sign check	Sign check
Webhook API reference	Webhook API