Webhooks

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.

Webhooks are created using our API. Please see the webhooks section for information specific to managing webhooks.

Settings

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.

Receiving a Notification

Webhook events are sent to the URL provided when creating a webhook. The endpoint should accept the request and return a 2xx status code. If a status code other than 2xx is 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.

Delivery Headers

Webhook events will be sent as HTTP POST requests to your webhook's URL. Each event will contain the following headers.

Header	Description
Malomo-Attempt-Number	Current attempt number for a webhook event
Malomo-Topic	Name of the topic that triggered the webhook attempt
Malomo-Webhook-Id	Unique identifier of the webhook used to send events
Malomo-Signature	Signature that can be used to verify the authenticity of a request. This header will only be provided if the webhook contains a secret. Please see the verification section for more details.
User-Agent	Set to Malomo-Webhook-Agent/2.0

Verification

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-Signature header 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-Signature header will not be sent as part of the request.

Topics

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.

• customers:created

• customers:deleted

• customers:updated

• events:created

• orders:created

• orders:deleted

• orders:updated

Webhook Body

The webhook body is identical to the response of the resource's REST endpoints. For example, a webhook event for the orders:created topic would correspond to the Order resource. Please see the resources section for examples of the response body for each resource type.