Webhooks

Webhooks let Melio notify your system when something changes, so you don’t have to poll. When a subscribed event occurs, Melio sends an HTTP POST to the endpoint you registered. Each partner has a single webhook endpoint. You manage it through the /webhook resource and choose which event types it receives.

Managing your endpoint

Method	Path	Description
`GET`	`/webhook`	Retrieve your endpoint and the events it’s subscribed to. Returns `404` if none is configured.
`PATCH`	`/webhook`	Create or update your endpoint.
`DELETE`	`/webhook`	Remove your endpoint. Melio stops sending deliveries.
`GET`	`/webhook/events`	List the event types you can subscribe to.

Creating or updating

PATCH /webhook is a partial update: only the fields you send are changed.

url and events are required the first time (when no endpoint exists yet).
Sending events replaces the entire subscription list, so always include the full set you want (at least one).
Set isActive: false to pause deliveries without deleting the endpoint, and true to resume.

curl -X PATCH https://api.example.com/v2/webhook \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://partner.example.com/webhooks/melio",
    "description": "Production endpoint",
    "events": ["api.entity.created", "api.account.updated", "api.payment.updated"]
  }'

The endpoint url must be an https URL.

Event types

Event	Fires when
`api.entity.created`	A business entity is created.
`api.entity.updated`	An entity changes, including when a risk decision is reached.
`api.account.created`	An account (internal or external) is created.
`api.account.updated`	An account changes, including when it becomes verified.
`api.account.deleted`	An account is deleted.
`api.payment.created`	A payment is created.
`api.payment.updated`	A payment changes (a status transition, an edit, or a cancellation).
`api.limitation.updated`	A business’s limitations change.

Delivery payload

Each delivery is a lightweight notification. It identifies the affected resource, not its full state. Treat the payload as a signal to fetch the current resource (for example GET /payments/{id}) rather than as the source of truth, so you never act on a stale snapshot. Every delivery includes these fields:

Field	Description
`event`	The event type (see above).
`messageId`	Unique event id, stable across retries. Use it for idempotency. Also sent as the `X-Melio-Delivery-Id` header.
`id`	The id of the affected resource (`ent_...`, `acct_...`, or `pay_...`).
`entityId`	The business entity that holds the resource.
`occurredAt`	When the change occurred (RFC 3339, UTC). See Timestamps.
`externalId`	Your own id for the affected resource, if one was set. See External IDs.
`entityExternalId`	Your own id for the holding entity, if one was set (present on account and payment events).
`metadata`	The affected resource’s metadata, if any was set.

Some events carry a small data object; most do not, and you should fetch the resource for its current state. Account created/deleted events include:

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

Verifying deliveries

Every delivery is signed so you can confirm it genuinely came from Melio and was not tampered with. The raw request body is signed with HMAC-SHA256 (hex encoded) using your API key secret, and the signature is sent in the X-Melio-Signature header. To verify, compute the HMAC over the raw request body (before any JSON parsing) and compare it to the header using a constant-time comparison:

import crypto from 'crypto';

function isValidSignature(rawBody, signatureHeader, apiKeySecret) {
  const expected = crypto
    .createHmac('sha256', apiKeySecret)
    .update(rawBody) // the raw bytes, not the parsed object
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  );
}

Verify the signature against the raw request body exactly as received. Re-serializing the parsed JSON can change byte-for-byte formatting and produce a different HMAC, causing valid deliveries to fail verification. Reject any delivery whose signature does not match.

Handling deliveries reliably

Be idempotent. The same event may be delivered more than once. Deduplicate on messageId (also available as the X-Melio-Delivery-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. Set isActive: false to stop deliveries during maintenance instead of tearing down and rebuilding your subscription.

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

Get started

Core resources

Building with the API

Risk, compliance & going live

Tools

Managing your endpoint

Creating or updating

Event types

Delivery payload

Verifying deliveries

Handling deliveries reliably

​Managing your endpoint

​Creating or updating

​Event types

​Delivery payload

​Verifying deliveries

​Handling deliveries reliably

​Related

Managing your endpoint

Creating or updating

Event types

Delivery payload

Verifying deliveries

Handling deliveries reliably

Related