> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesh.larkwave.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Events, signatures, retries and replays.

Mesh sends every event for a mode to one URL of yours. Your code switches on `event`.

## Set your URL

```bash theme={null}
curl -X PUT https://$MESH_HOST/v1/webhook-endpoint \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/larkwave" }'
```

The first time, the answer includes `secret` (`whsec_…`). **It's shown only then.** Store it; it signs every webhook.

* Test and live have separate URLs and secrets: a test key sets the test URL.
* The URL must be a public `https` address (`http` only in test). Addresses that resolve to private or local networks are refused.
* `DELETE /v1/webhook-endpoint` stops deliveries. `PUT` with `"enabled": false` pauses them.

## What you receive

```http theme={null}
POST /larkwave
Content-Type: application/json
Mesh-Event-Id: evt_01a190e0622270bd842caf50cee816ec
Mesh-Delivery-Id: 01a190e0-6254-7294-b81c-f5110ebc0d14
Mesh-Signature: t=1793431991,v1=5f2b…

{
  "id": "evt_01a190e0622270bd842caf50cee816ec",
  "event": "va.payment.success",
  "mode": "test",
  "business_id": "11111111-1111-1111-1111-111111111111",
  "occurred_at": "2026-10-25T09:00:00+00:00",
  "data": {
    "virtual_account_id": "9b2e4c1a-…",
    "account_number": "6037000014",
    "amount_minor": 150000,
    "sender_name": "ADA OBI",
    "session_id": "000013251025090000123456789012",
    "transaction_id": "0f3c2b1a-…"
  }
}
```

Answer any `2xx` within 10 seconds. Do your processing after you answer.

## Verify the signature

`Mesh-Signature` is `t=<unix seconds>,v1=<hex>`. For each `v1`, compute `HMAC-SHA256(secret, t + "." + raw body)` as hex, and accept when any matches, compared in constant time. Refuse a `t` more than 5 minutes old.

```javascript Node.js theme={null}
import crypto from "node:crypto";

export function verify(header, rawBody, secret) {
  const parts = header.split(",").map((p) => p.split("="));
  const t = parts.find(([k]) => k === "t")?.[1];
  const signatures = parts.filter(([k]) => k === "v1").map(([, v]) => v);
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= 300;
  return fresh && signatures.some((v) =>
    v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}
```

```python Python theme={null}
import hashlib, hmac, time

def verify(header: str, raw_body: bytes, secret: str) -> bool:
    parts = [p.split("=", 1) for p in header.split(",")]
    t = next(v for k, v in parts if k == "t")
    signatures = [v for k, v in parts if k == "v1"]
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(t)) <= 300
    return fresh and any(hmac.compare_digest(v, expected) for v in signatures)
```

> [!WARNING]
>
> Verify against the **raw** body bytes, before any JSON parsing. Re-serialised JSON won't match.

## Delivery

* **At least once.** The same event can arrive more than once, and a replay carries the same id. Deduplicate on `Mesh-Event-Id`.
* **Retries.** Anything but a `2xx` within 10 seconds is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, then every 12 hours, for up to 3 days.
* **Failing URLs.** When a delivery runs out of retries, the URL shows `failing_since` and your team gets one email. The next successful delivery clears it. Mesh never disables your URL.
* **History.** `GET /v1/webhook-deliveries` lists deliveries; `GET /v1/webhook-deliveries/{deliveryId}` shows each attempt, with the status and the start of your answer.
* **Replay.** `POST /v1/webhook-deliveries/{deliveryId}/retry` sends it again now.
* **Test.** `POST /v1/webhook-endpoint/test` sends a `webhook.test` event.
* **Kept for 30 days**, then deleted.

## Rotate the secret

`POST /v1/webhook-endpoint/rotate-secret` returns a new secret. For 24 hours every webhook carries two `v1` signatures, one per secret, so you can switch without missing any.

## Events

| Event | When |
| - | - |
| `va.created`, `dva.created` | An account was made |
| `va.name.confirmed`, `va.name.failed` | The provider named an account, or refused |
| `va.payment.success`, `.held`, `.accepted`, `.returned` | A payment into a collection account |
| `dva.payment.success`, `.held`, `.accepted`, `.returned` | A payment into a one-off account |
| `dva.expired`, `dva.cancelled` | A one-off account ended |
| `va.settlement.completed`, `va.settlement.failed` | A payment passed on to your account at the bank |
| `wallet.credited` | Money into one of your wallets or a customer's |
| `transfer.interbank.settled`, `.failed`, `.reversed` | An interbank transfer's outcome |
| `settlement.settled`, `.failed`, `.reversed` | A settlement's outcome |
| `account.restricted`, `account.unrestricted` | A restriction placed or lifted |
| `collection.requested`, `.modification_requested`, `.approved` | Your business's request to collect |
| `collection.pattern_allocated`, `.pattern_retired` | A number pattern given or retired |
| `webhook.test` | You asked for a test |

## Polling instead

`GET /v1/events` lists the same events, newest first, with the same `data` (filters `event`, `from`, `to`). `GET /v1/events/{eventId}` reads one. Use it to catch up after downtime, or instead of webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.