Webhooks Data Structure
- Michal Gregor
Data structure used in webhooks is described in further sections below.
Hook body structure
All hooks are sent as HTTP POST requests.
Hook request body consist of:
Event metadata:
Field name | Mandatory | Format | Description |
|---|---|---|---|
eventId | yes | UUID v4 | unique ID of an event. This might be used to prevent duplicate processing of events on consumer’s side. |
eventType | yes | string | type of hook |
eventTimestamp | yes | UTC timestamp in ISO format | Timestamp of event creation (e.g. when payment’s state was changed). Consumers should consume only events that are newer than last consumed event. |
Event Data. Contains event data as well as multiple identifiers. Also, custom hookData can be specified for an instance of an payment or order entity (at the time of initiation via API). All described fields are enclosed in a
dataproperty (see example):
Field name | Mandatory | Format | Description |
|---|---|---|---|
paymentId | only for payments | UUID v4 | ID of a payment in Everifin Paygate. One of paymentId/refundId is always specified. |
refundId | only for refunds | UUID v4 | ID of a refund in Everifin Paygate, in case the entity is a refund payment. One of paymentId/refundId is always specified. |
orderId | no | UUID v4 | If API v2 is used, orderId is specified. |
instructionId | no | UUID v4 | InstructionId of a payment/refund, if specified by client during payment/refund creation. |
externalId | no | UUID v4 | ExternalId of an order, if specified by client during order creation. |
status | depends on hook type | string | For statusChange hooks, status specifies the new entity status. For possible values of Payment statuses, see Paygate Payment Flow | Payment statuses For possible values of Order statuses, see Paygate Payment Flow | Order statuses |
hookData | no | JSON | Custom hookData specified by client during payment/order entity creation (via API). HookData object is always sent with hooks related to given entity. |
For example, a structure of request body for payment.statusChange would look like this:
{
"eventId": "4e896aa3-bbba-4a75-a888-06bcfe403c99",
"eventType": "payment.statusChange",
"eventTimestamp": "2023-12-21T20:34:59.895Z",
"data": {
"paymentId": "f0489615-fb8a-4c76-bb28-7f9726d815d6",
"orderId": "8840d948-12da-4ca1-8269-3cfdc10b73bc",
"status": "PROCESSING",
"instructionId": "302d7603-f5ce-45fb-82b3-a1a90ee26aca",
"hookData": {
"customId": 12341234,
"note": "order x54352"
}
}
}