Skip to main content

Introduction to Webhooks

Webhooks let your integration receive events from OMS as they happen. Webhooks are enabled and configured for you by Calicantus: to register your endpoint URL, choose the events to receive, or set the authentication credentials and custom headers, contact developers@calicant.us.

Endpoint requirements​

  • must be able to receive HTTP POST requests on the specified URL
  • must support TLS, even with self-signed certificates
  • must respond within a 10 second timeout

Supported authentication methods​

Retry policy​

A request is considered failed if:

  • any status code other than 200 is received
  • no response is received within the 10 second timeout described in the endpoint requirements

In case of failure, a limited number of retries will be made with exponential backoff.

If all retry attempts fail, the request will be considered permanently failed.

Every retry delivers the same event with the same id: since your endpoint may receive the same event more than once (for example when it processes the request but responds after the timeout), use the event id to make sure each event is processed only once.

Event payload​

Example:

{
    "id": "01929acb-f539-74a9-964f-b04bc76ae78b",
    "data": {
        "id": 1234,
        "resource": "PaymentExternalTransaction",
        "event": "refund_requested",
        "timestamp": "2024-10-17T08:00:30+00:00",
        "payload": {}
    }
}

Description:

  • id: UUIDv7 that uniquely identifies the event
  • data.id: ID of the resource that triggered the event
  • data.resource: name of the resource that triggered the event
  • data.event: type of event
  • data.timestamp: timestamp of the event occurrence in ISO8601 format
  • data.payload: additional event-specific data, shown empty in the envelope example above — the content of each event's payload is documented in Events

Headers​

The HTTP request will by default contain the following headers:

  • Content-Type: application/json
  • OMS-Webhooks-Version: version of the payload, currently always set to v1

Additional custom headers can also be set during configuration.