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 — a self-signed certificate works only if certificate verification is disabled for your endpoint, which is part of its configuration
- must respond within a 10 second timeout
You can exercise all of this before your webhook is configured: the Webhook tester builds the exact request the OMS sends for an event, ready to run against your endpoint.
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 — how many attempts is part of your endpoint's configuration.
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 eventdata.id: ID of the resource that triggered the eventdata.resource: name of the resource that triggered the eventdata.event: type of eventdata.timestamp: timestamp of the event occurrence in ISO8601 formatdata.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/jsonOMS-Webhooks-Version: version of the payload, currently always set tov1Accept: */*Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3User-Agent: the HTTP client the OMS calls you with, currentlyrest-client/2.1.0 (linux x86_64) ruby/3.2.2p53— it changes when the client is upgraded, so do not make your endpoint depend on its value
The authentication you configure adds an Authorization header, and any custom header set during configuration is sent as provided.