Introduction

Webhooks allows the client to set a callback URL on which the client will receive a POST request containing event data relating to a specific system event or API request.

An event may be raised as the outcome of a specific operation initiated by a client via Order Management API, and Checkout API.

info

When a new payment method is added Update Subscription needs to be called , to get the events for the new payment method.

URL requirements

• Webhook URLs must accept HTTPS connections using TLS v1.2 or higher.
• Webhook URLs must accept POST requests.
• Webhook URLs must accept media type “application/json”.
• Webhook URLs must indicate successful reception of event by returning 2xx response.

Request Body

The body of a webhook request contains event data with mandatory fields as well as event specific fields based on the type of operation that caused the event to be raised.

Mandatory fields

Name	Description	Type
EventName	The event type, this is used to determine the type of event received.	String
CorrelationId	The correlation id provided in the origin request if the event is raised based on the outcome of a client-initiated operation.	Guid
TimestampUtc	A timestamp representing the moment in time when the event was raised.	Timestamp

Delivery Guarantees

• Events might be delivered more than once, so duplicates are possible.
• Events are not guaranteed to be delivered in chronological order.
• Events are not guaranteed to be delivered in scenarios where the receiving webhook endpoint is unavailable.
• If a request does not receive a 2xx response, the system will retry with exponential backoff over a set period until a maximum number of attempts is reached or a successful response is received.

info

To avoid some failures and to minimize retries Svea recommends a few practices when integrating support for webhook events.

Recommendations

• Since the webhook URL can be invoked more than once for the same event, we recommend that clients make their event processing idempotent. This is to avoid duplicates on the client side.
• We recommend that the client adds the incoming events to a queue for future processing so that a response can be returned to our API as quickly as possible.
• Since event delivery is not guaranteed if the client endpoint is unavailable for the full retry attempt duration, we recommend that data is also synched through GET Order
• A good practice is also to implement support for full order sync when receiving the generic order updated event for an order.