​

Configuration

To use Meso webhooks, you will need to provide endpoint(s) for delivery. For both sandbox and production environments, your endpoint must:

• be served via HTTPS
• return a 2xx status code (typically a 200 or 202) to confirm receipt. Non-2xx status codes will be considered as failures.

​

Testing webhooks

To ensure your system is receiving and handling Meso webhooks correctly, you should first test against the Meso sandbox.

When testing in sandbox, you may be working with a version of your system running locally. In this case, it is recommended to use a tool such as ngrok to forward your local address (localhost) to a qualified domain. You can also use a tool such as webhook.site to test incoming payloads.

​

Test events

You can send test events to your webhook endpoint in both sandbox and production to verify your connectivity.

To send a test event, call the notifications/test endpoint.

​

Integrity/Security

​

Payload signatures

The body of each Meso webhook is signed with your API key(s) so you can verify they originated from Meso. The signature hash is sent via the the x-signature header.

To verify the received webhook, you will need to prepare an HMAC with a SHA-256 hash of the inbound request body and compare the result to the value(s) in the signature headers.

import { timingSafeEqual, createHmac } from "crypto";

const API_KEY = "<your_api_key>";

app.post("/meso-webhooks", async (req, res) => {
  const mesoSignature = app.headers.get("x-signature");
  const signature = createHmac("sha256", API_KEY)
    .update(req.body)
    .digest("hex");

  // Verify signatures match
  if (timingSafeEqual(Buffer.from(mesoSignature), Buffer.from(signature))) {
    // Handle webhook payload
    res.status(200).end();
  }

  // Send a 4xx response and ignore processing of the payload
});

​

Failures & Retries

A webhook delivery is considered to have failed if:

• Meso receives a non-2xx response code
• No response is received within 5 seconds

Upon failure, Meso will attempt to redeliver the webhook 5 more times at the following intervals:

• 1 minute
• 5 minutes
• 15 minutes
• 25 minutes
• 60 minutes

After all retries have been exhausted, no more attempts will be made and the event cannot be recovered.

​

Events

Webhook events are POST requests that will contain JSON bodies and the following request headers:

• content-type: application/json
• user-agent : meso/1.0.0
• x-signature : A computed hash of the request body using your API key (HMAC with SHA-256 encoding)

​

Event ordering

Meso will make every effort to deliver events in order. However, depending on whether a delivery is retried or not, webhooks may arrive out of order. You should verify each received webhook’s event_time timestamp to ensure correct processing.