Dispatching Webhook notifications

What is a Webhook?

A webhook is a technology that enables real-time communication between systems. It works by sending automated messages or data to a specified URL when certain events occur. Unlike traditional APIs, which require constant polling for updates, webhooks push information immediately as the event happens, making them efficient for triggering actions or updating systems in real time.

Webhook Implementation in WISMOlabs

Within the WISMOlabs platform, every process, such as order shipment or return, is driven by a series of events. For example, an outbound shipment may progress through stages like packaging, pickup by the carrier, shipping, out for delivery, and final delivery. Other events might include customs clearances for international deliveries, delays, failed delivery attempts, or a return to sender. Similarly, a return process could involve return request initiation, return request approval, shipment back to the return processing center, verification, and refund issuance. Each of these steps is an event that can trigger a webhook notification.

Webhook notifications are vital for keeping your entire technological stack in sync, ensuring all systems are updated with the latest status changes. WISMOlabs offers fully configurable webhook payloads that can be customized using the Liquid templating language. All webhook payloads must be valid JSON format. Please ensure compatibility with your systems.

• Outbound shipment (orders) webhooks are managed via Settings > Alerts > Webhooks.
• Inbound shipments (returns) webhooks are managed via Settings > Returns > Webhooks.

This flexibility allows retailers to ensure all aspects of their order and return processes are aligned and responsive to customer needs in real time.

Verifying Webhooks with Signature

Because webhooks are delivered as HTTP POST requests to a public endpoint, your application must verify that each request was actually sent by WISMOlabs before processing it.

Each webhook attempt includes signed metadata that lets you verify both authenticity and integrity.

Headers used for verification

Each webhook request includes these headers:

• svix-id: the unique message identifier for the webhook attempt
• svix-timestamp: the timestamp of the webhook attempt in seconds since epoch
• svix-signature: one or more versioned signatures, usually in the format `v1,<signature>`
  
  

Important verification rule

The signature is not computed from the request body alone.
To verify a webhook manually, construct the signed content exactly like this:

`svix-id + "." + svix-timestamp + "." + raw_request_body`

Then:

1. Take your endpoint Signing Secret.
2. Remove the `whsec_` prefix.
3. Base64-decode the remaining value into bytes.
4. Compute an HMAC-SHA256 using the decoded secret bytes as the key and the signed content above as the message.
5. Base64-encode the raw HMAC digest.
6. Compare the result to the value in `svix-signature` after removing the version prefix such as `v1,`.

If the signature header contains multiple space-delimited signatures, compare against each valid signature value.

Use the raw request body

Use the raw request body exactly as received.

Do not parse and re-serialize the JSON before verifying the signature. Even small formatting changes, such as whitespace, escaping, or field ordering, can cause verification to fail.

Verify timestamp

You should also validate timestamp and reject requests that fall outside a small time tolerance. This helps protect against replay attacks.

Finding your Signing Secret

You can look up and rotate the unique Signing Secret for your endpoint in the WISMOlabs admin area.

For shipment notification webhooks, go to Settings > Webhooks > Logbook, then open the endpoint and view `Signing Secret`.

Ensuring JSON Consistency in Liquid Templates

Note: It is extremely important to ensure that the rendered Liquid template results in valid JSON format. When using Liquid variables that may have no or null values, use the default filter to maintain JSON consistency. This ensures the value is wrapped in brackets and the JSON remains valid. For example, when handling optional values, use:

"parameter": {{payload.optional.OPTIONAL_VALUE | default: ''}}

Webhook Deliverability and Retry Schedule

If your configured endpoint fails to retrieve a webhook payload due to unavailability and does not respond with a 200 OK message, WISMOlabs will retry using an exponential backoff schedule:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

This gives you time to fix a potentially broken endpoint without bottlenecking the system with failing messages.