Webhooks

Setting up your endpoint

1. Enter your Endpoint URL. It must be an https URL.
2. Choose the events you want to receive (see Event types). You must select at least one.
3. Select Save endpoint.

• Edit the URL or the subscribed events. Saving replaces the whole event list.
• Pause deliveries without deleting the endpoint, and resume them later. See Retries and failure handling for what happens to events while paused.
• Rotate the signing secret.
• Delete the endpoint. Melio stops sending deliveries. Registering a new endpoint later creates a new signing secret.

Event types

Delivery payload

{
  "event": "api.account.created",
  "messageId": "evt_...",
  "id": "acct_...",
  "entityId": "ent_...",
  "occurredAt": "2026-07-08T15:04:05Z",
  "data": {
    "ownershipType": "external",
    "accountType": "ach"
  }
}

Verifying deliveries

Request headers

Verifying with the Standard Webhooks library

import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.MELIO_WEBHOOK_SECRET); // whsec_<base64>, exactly as shown in the portal

app.post('/melio/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = wh.verify(req.body.toString('utf8'), req.headers); // throws if invalid or older than 5 min
    handle(event);
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});

Verifying without a library

import crypto from 'crypto';

// whsec_<base64>: the HMAC key is the base64 part
const secret = Buffer.from(process.env.MELIO_WEBHOOK_SECRET.replace(/^whsec_/, ''), 'base64');
const TOLERANCE_SECONDS = 300;

function isValidMelioWebhook(rawBody, headers) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatureHeader = headers['webhook-signature'];
  if (!id || !timestamp || !signatureHeader) return false;

  // Reject old deliveries (replay protection)
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  // Sign id.timestamp.rawBody, using the raw body before any JSON parsing
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();

  // The header may hold several signatures ("v1,abc v1,def"); one match is enough
  return signatureHeader.split(' ').some((entry) => {
    if (!entry.startsWith('v1,')) return false;
    const received = Buffer.from(entry.slice(3), 'base64');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

Rotating the signing secret

• Keep the old secret valid for 24h (default). For the next 24 hours every delivery is signed with both the old and the new secret, and webhook-signature carries both signatures. Your verifier keeps accepting deliveries with either secret, so you can deploy the new secret at any point in that window without dropping events. After 24 hours only the new secret signs.
• Rotate now. The old secret stops signing immediately. Use this if the secret may have leaked. Deliveries are signed only with the new secret, so update your verifier first or expect failed verifications until you do.

Handling deliveries reliably

• Verify every delivery. Check the signature and the timestamp before you trust the payload.
• Be idempotent. The same event may be delivered more than once. Deduplicate on messageId (also sent as the webhook-id header) so you process each event only once.
• Respond quickly with a 2xx. Acknowledge receipt fast and do heavy work asynchronously. Failed deliveries are retried.
• Fetch current state. Because deliveries are notifications, always read the resource (GET) to get its latest state before acting, rather than trusting a possibly out-of-order payload.
• Pause safely. Pause the endpoint in the portal to stop deliveries during maintenance instead of deleting and recreating it. Note that events that occur while paused are dropped (see below).

Retries and failure handling

Retry schedule

1. Within seconds of the event occurring.
2. About 45 minutes after attempt 1.
3. About 45 minutes after attempt 2.

What gets retried

Paused endpoints

Staying correct across retries

• Deduplicate on messageId. The same messageId is used for every attempt of the same event, so it is a stable idempotency key. It is also sent as the webhook-id header. Treat a delivery whose messageId you have already processed as a no-op and return 2xx.
• Don’t assume ordering. A retried delivery can arrive after newer events for the same resource. A retried api.payment.updated may land after the payment has moved on again. Always GET the resource and act on its current state rather than on the payload, and never rely on occurredAt ordering to drive a state machine.
• Respond quickly. Acknowledge with a 2xx as soon as the delivery is persisted, and do heavy work asynchronously. A slow handler burns the attempt and forces an unnecessary retry.
• Expect a fresh timestamp on a retry. Each attempt is signed at the time it is sent, so the 5-minute timestamp check in your verifier applies to retries as well.

Related

• Timestamps - the occurredAt format.
• External IDs - correlating events to your own records.
• Metadata - extra context carried on deliveries.