To get started with the Meso Partner API and webhooks, you will need a Meso Partner ID and API Keys which you can request here.

Currently, webhooks are not self-service. Meso will work with your team to set up your webhook endpoints and provide API keys.

​
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.

Since webhooks currently require manual configuration, consider using ngrok’s custom domains or webhook.site’s custom addresses features to allow for easier iteration.

​
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.

Using the APIReference