Webhooks data structure

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 data property (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.
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"
        }
    }
}