Webhooks - Meru

Webhooks let you receive real-time notifications when a payout or a crypto deposit changes state. When an event occurs, we send a signed POST request to your configured webhook endpoint with the event body.

Configuring your endpoint

Your endpoint must be publicly reachable over HTTPS and respond with any 2xx status code. Configure its URL with your Meru contact or via the dashboard. On creation you receive a signing secret (prefixed with whsec_) — store it securely; you need it to verify signatures.

Event structure

Every delivery body has the same top-level shape:

{
  "type": "payout.update",
  "timestamp": "2026-06-23T12:00:00.000Z",
  "data": { }
}

type

string

The event type. One of payout.update or balance.updated.

timestamp

string

ISO 8601 timestamp of when the event was emitted.

data

object

The event payload. Its shape depends on type (see below).

Delivery headers

Each request includes these headers:

Header	Description
`Content-Type`	`application/json`
`webhook-id`	Unique message/delivery ID. Use it for idempotency.
`webhook-timestamp`	Unix timestamp (seconds) of the delivery, used for signature verification.
`webhook-signature`	Space-separated list of `v1,<base64>` signatures (more than one during secret rotation).

Verifying signatures

Each request is signed with HMAC-SHA256 so you can confirm it came from us. The signed content is the string {webhook-id}.{webhook-timestamp}.{rawBody}, keyed with your signing secret (base64-decoded after stripping the whsec_ prefix), and the result is base64-encoded into the webhook-signature header. To verify: recompute the signature over the raw request body (before any JSON parsing) and compare it against the header in constant time. Reject deliveries whose webhook-timestamp is more than 5 minutes old.

import crypto from "crypto";

function verifySignature(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const header = headers["webhook-signature"]; // "v1,<base64> v1,<base64>"

  // Reject deliveries older than 5 minutes
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const signedContent = `${id}.${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", key)
    .update(signedContent)
    .digest("base64");

  // The header can carry multiple space-separated "v1,<sig>" entries
  return header.split(" ").some((part) => {
    const sig = part.split(",")[1];
    return (
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
    );
  });
}

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  // req.body is the RAW body (Buffer/string), not parsed JSON
  if (!verifySignature(req.body.toString(), req.headers, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  const event = JSON.parse(req.body); // { type, timestamp, data }
  handleWebhookEvent(event);
  res.status(200).json({ received: true });
});

Event: `payout.update`

Sent whenever a payout changes state. The event type is always payout.update regardless of the transition — read data.state (and data.previousState) to know what happened.

`data` fields

payoutId

string

The payout identifier.

companyId

string

Your company identifier.

externalId

string

Your external reference, if one was provided.

onBehalfOf

string

The end user/entity the payout was made for.

previousState

string | null

The state before this transition. null on the first event (creation).

state

string

The current payout state. See the table below.

amount

number

The payout amount, in minor units (e.g. cents).

currency

string

The destination currency.

destinationType

string

One of wallet, bank, or qr_code.

errorReason

string

Present only when the payout failed.

txHash

string

On-chain transaction hash. Present for wallet and bank destinations.

extraData

object

Bank-rail metadata. Present only for destinationType = bank.

Show extraData

finalAmount

string

Final settled amount.

finalAmountCurrency

string

Currency of the settled amount.

uetr

string

SEPA/SWIFT unique end-to-end transaction reference.

trackingNumber

string

Tracking number.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-update timestamp.

Payout states (`data.state`)

State	Meaning
`created`	Payout created
`in_review`	In review (pre-partner)
`awaiting_funds`	Awaiting funds
`funds_received`	Funds received
`payment_submitted`	Submitted / in progress
`payment_processed`	Completed successfully
`undeliverable`	Undeliverable
`returned`	Returned
`refunded`	Refunded
`canceled`	Canceled
`error`	Error / failed

{
  "type": "payout.update",
  "timestamp": "2026-06-23T12:00:00.000Z",
  "data": {
    "payoutId": "3ddd0e5b-6276-4b48-b756-c1fcc9a2efd1",
    "companyId": "cmp_123",
    "externalId": "ext-001",
    "onBehalfOf": "user-123",
    "previousState": "payment_submitted",
    "state": "payment_processed",
    "amount": 100000,
    "currency": "cop",
    "destinationType": "bank",
    "txHash": "0xabc123",
    "extraData": {
      "finalAmount": "99950",
      "finalAmountCurrency": "cop",
      "uetr": "97ed4827-7b6f-4b1a-9b0e-2a1c3d4e5f60",
      "trackingNumber": "TRK-0001"
    },
    "createdAt": "2026-06-23T11:00:00.000Z",
    "updatedAt": "2026-06-23T12:00:00.000Z"
  }
}

Event: `balance.updated`

Sent when a crypto deposit changes state. Its data shape differs from payout.update: it carries on-chain deposit details and does not include onBehalfOf, destinationType, or extraData.

`data` fields

payoutId

string

The deposit identifier (named payoutId for transport consistency).

companyId

string

Your company identifier.

externalId

string

Your external reference, if one was provided.

previousState

null

Always null for deposit events.

state

string

The current deposit state.

amount

number

The deposit amount, in minor units.

currency

string

The deposit currency (e.g. usdc).

blockchain

string

The blockchain the deposit settled on.

txHash

string | null

On-chain transaction hash, when available.

errorReason

string | null

Failure reason, when applicable.

updatedAt

string

ISO 8601 last-update timestamp.

{
  "type": "balance.updated",
  "timestamp": "2026-06-23T12:00:00.000Z",
  "data": {
    "payoutId": "dep_9f86d081884c7d65",
    "companyId": "cmp_123",
    "externalId": "ext-009",
    "previousState": null,
    "state": "funds_received",
    "amount": 100000,
    "currency": "usdc",
    "blockchain": "ethereum",
    "txHash": "0xdef456",
    "errorReason": null,
    "updatedAt": "2026-06-23T12:00:00.000Z"
  }
}

Idempotency

The same event may be delivered more than once. Use the webhook-id header as the idempotency key: store processed IDs and skip duplicates.

Retries

If your endpoint does not return a 2xx status (or times out), we retry delivery automatically with exponential backoff over several hours, honoring Retry-After on error responses. Acknowledge quickly (under a few seconds) and process heavy work asynchronously. Endpoints that fail persistently may be disabled.

Best practices

Always verify the signature against the raw body before processing.
Respond fast with a 2xx, then process asynchronously.
Be idempotent using webhook-id.
Don’t assume order — rely on state/previousState and updatedAt, not delivery order.
Log the webhook-id, type, and data.state for every delivery.

Example handler

import express from "express";
import crypto from "crypto";

const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString();
  if (!verifySignature(raw, req.headers, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(raw);
  switch (event.type) {
    case "payout.update":
      console.log(
        `Payout ${event.data.payoutId}: ${event.data.previousState} → ${event.data.state}`,
      );
      break;
    case "balance.updated":
      console.log(`Deposit ${event.data.payoutId}: ${event.data.state}`);
      break;
    default:
      console.warn(`Unhandled event type: ${event.type}`);
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log("Webhook server listening on port 3000"));

Testing

Expose your local server with a tunnel (e.g. ngrok) and register the public URL as your webhook endpoint:

ngrok http 3000

Troubleshooting

Invalid signature: verify against the raw body (not re-serialized JSON), use the correct whsec_ secret, and read the webhook-id/webhook-timestamp/webhook-signature headers as-is.
Duplicate events: deduplicate using webhook-id.
Missed events: ensure your endpoint returns 2xx quickly; non-2xx responses and timeouts are retried, but persistent failures can disable delivery.
SSL errors: your endpoint needs a valid TLS certificate.

For help with a specific delivery, contact support with the webhook-id.

​Configuring your endpoint

​Event structure

​Delivery headers

​Verifying signatures

​Event: payout.update

​data fields

​Payout states (data.state)

​Event: balance.updated

​data fields

​Idempotency

​Retries

​Best practices

​Example handler

​Testing

​Troubleshooting

Configuring your endpoint

Event structure

Delivery headers

Verifying signatures

Event: `payout.update`

`data` fields

Payout states (`data.state`)

Event: `balance.updated`

`data` fields

Idempotency

Retries

Best practices

Example handler

Testing

Troubleshooting