Webhooks

This document provides an in-depth explanation of how the API Platform dispatches webhooks. It covers the webhook dispatch flow, retry logic, timeout settings, endpoint requirements, payload structure, and best practices for integrating with the webhook system.

Overview

Webhooks allow external systems to receive real-time notifications when certain events occur within the API Platform. This mechanism ensures that your application stays synchronized with the changes happening in the system. The webhook dispatch system is designed with robust retry logic, strict timeout settings, and clear payload structures to ensure reliable and predictable delivery.

Webhook Structure

All Webhooks dispatched from the API Platform follow a consistent structure. Each webhook event is sent as a JSON payload in a POST request to a specified endpoint. The payload contains the following key elements:

• eventId: A unique identifier for the event.
• eventType: The type of event that occurred.
• eventTime: The timestamp when the event was triggered.
• objectType: The type of object that the event relates to (e.g., order, product, location).
• newState: The new state of the object after the event occurred.
• previousState: The previous state of the object before the event occurred (if applicable).

Example Event Payload:

{
  "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "clientId": "5e505642-9024-474d-9434-e5a44f505cc5",
  "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",
  "locationId": "1a5515a3-ba81-4a42-aee7-ad9ffc090a54",
  "eventTime": "2019-08-24T14:15:22Z",
  "connectionId": "84b500d7-71c8-4b1f-adf4-f1eb0000973d",
  "eventType": "INSERT",
  "newState": {
    "nextAutoPublishAt": "2019-08-24T14:15:22Z",
    "autoPublishInterval": 0,
    "resellerId": "fbea2d74-a85a-498f-90ae-2366ba4a76ca",
    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    "createdAt": "2019-08-24T14:15:22Z",
    "lastMenuSyncedAt": "2019-08-24T14:15:22Z",
    "locationId": "1a5515a3-ba81-4a42-aee7-ad9ffc090a54",
    "failureReason": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
    "status": "PENDING",
    "lastMenuSyncId": "eb2f7a41-e884-4b07-9903-ea987ba6d868",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "objectType": "CONNECTION",
  "previousState": {
    "nextAutoPublishAt": "2019-08-24T14:15:22Z",
    "autoPublishInterval": 0,
    "resellerId": "fbea2d74-a85a-498f-90ae-2366ba4a76ca",
    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    "createdAt": "2019-08-24T14:15:22Z",
    "lastMenuSyncedAt": "2019-08-24T14:15:22Z",
    "locationId": "1a5515a3-ba81-4a42-aee7-ad9ffc090a54",
    "failureReason": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
    "status": "PENDING",
    "lastMenuSyncId": "eb2f7a41-e884-4b07-9903-ea987ba6d868",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Webhook Dispatch Flow

When an event occurs that requires a webhook notification, the API Platform dispatches a POST request to your webhook endpoint. The following sections outline the key elements of this process.

HTTP Method and Content Type

• HTTP Method: All webhook events are dispatched using the POST method.
• Content Type: The request must have a Content-Type header set to application/json. This ensures that the payload is parsed correctly by your endpoint.

Endpoint Requirements

• No Redirects: Your webhook endpoint must not implement any redirection flows. The endpoint should process the incoming request directly without forwarding it elsewhere.
• Response Handling: Your endpoint should respond with an HTTP status code of 2XX to indicate successful receipt of the webhook event. If the endpoint responds with any other status code, it will be marked as failed and depending on the status code, it may be retried.
• Security: To ensure data integrity, the webhook endpoint should implement security measures such as SSL/TLS encryption and request validation.

Request Timeout

• Timeout Setting: Webhook requests are configured to timeout after 29 seconds.
• Implication: If your endpoint does not respond within 29 seconds, the request will be terminated, and the event will be marked for a retry according to the retry policy.

Retry Policy

To maximize reliability, the API Platform incorporates a retry mechanism for webhook events. This helps to mitigate transient issues and network errors.

Retryable Status Codes

The following HTTP status codes are considered retryable errors. If your endpoint responds with any of these codes, the webhook event will be retried:

Status Code	Meaning	Description
429	Too Many Requests	Indicates that rate limiting has been applied.
500	Internal Server Error	The server encountered an unexpected error.
502	Bad Gateway	Received an invalid response from an upstream server.
503	Service Unavailable	The server is temporarily unable to handle the request.
504	Gateway Timeout	The upstream server failed to respond in time.

If a response with any of the above status codes is received, the webhook dispatch system treats the event as not successfully delivered and schedules a retry according to the above timing.

See the Retry Policy Guide for more details on how retries are managed.