Webhooks Docs — Mozaca Labs

ReferenceUpdated May 28, 2026

Overview

Webhooks notify your backend when a resource changes. Use them for transfer settlement, failed movement, approval changes, ledger reconciliation, and evidence export state.

Your endpoint must be publicly reachable over HTTPS in pilot or production. For sandbox testing, a temporary request inspector can be useful, but production endpoints should be owned by your infrastructure team.

Create a subscription

Webhook subscriptions are configured during sandbox review or through the webhooks API when enabled for your organization.

POST /webhook-subscriptionsjson

{
  "url": "https://example.com/mozaca/webhooks",
  "events": [
    "transfer.settled",
    "transfer.failed",
    "approval.updated",
    "ledger.matched"
  ],
  "description": "Sandbox event receiver"
}

Event shape

Events include an id, type, created timestamp, environment, and resource payload. Store event IDs so replayed deliveries do not process twice.

Transfer settled eventjson

{
  "id": "evt_01J0MZ7D9W",
  "type": "transfer.settled",
  "environment": "sandbox",
  "createdAt": "2026-05-28T10:42:18Z",
  "data": {
    "transferId": "tr_9K42",
    "status": "settled",
    "rail": "partner_mobile_money",
    "ledgerState": "matched"
  }
}

Verify signatures

Verify every webhook signature before processing the event. Reject unsigned payloads and payloads whose timestamp is outside your allowed tolerance.

Signature headershttp

Mozaca-Signature: t=1779964938,v1=...
Mozaca-Event-Id: evt_01J0MZ7D9W

Retries

Return a 2xx status only after your system has durably stored the event. Non-2xx responses may be retried. Webhook delivery order is not guaranteed, so process events by resource state and event timestamp.