Malomo can send webhook events that notify your application any time an event happens on your account. This can be useful for events -- like shipment updates -- that are not triggered by a direct API call. Webhooks can also be useful for services that are not directly responsible for making an API request but still need to know the response from that request.
All webhook events are sent with JSON-encoded request bodies.
A webhook is made up of three parts. A destination URL that webhook events will be sent to, a topic defining what type of events to send and an optional secret that can be used as a key to verify the authenticity of a request. A webhook will only receieve events for the topic it is subscribed to. You must register a webhook for each topic you want to subscribe to.
Webhook events are sent to the URL provided when creating a webhook. The endpoint should accept the request and return a
2xxstatus code. If a status code other than
2xxis returned the request will be considered unsuccessful and another request will be scheduled using an exponential backoff algorithm.
We will attempt to deliver an event up to 10 times over a 24 hour period. A request will timeout and be considered unsuccessful if it is not processed within 10 seconds. As a best practice it is recommended to perform any processing of the event asynchronously (e.g. a background job) and return a response as quickly as possible.
Webhook events will be sent as HTTP
POSTrequests to your webhook's URL. Each event will contain the following headers.
Malomo can optionally sign the event requests it sends to your webhook URL's. When a webhook is configured with a secret we will include an
Malomo-Signatureheader on each request.
The header will contain a string that is a cryptographically signed signature of the response body. The signature is computed using the HMAC-SHA256 algorithm with the webhook secret as the key.
If the webhook does not have a secret then the
Malomo-Signatureheader will not be sent as part of the request.
A topic specifies the type of event sent to a webhook. Each webhook can listen to only one topic. If you need to listen for multiple topics you can create a webhook for each topic.
Possible topics include.