Integrations · Event-driven

Webhooks

Receive real-time HTTP callbacks when payments complete, fail, or transactions settle. Register endpoints via the API and verify payloads with your webhook secret.

Register a webhook

POST to /webhooks with your callback URL and subscribed events.

Request

{
  "url": "https://your-server.com/bitmessa/webhook",
  "events": ["payment.completed", "payment.failed", "transaction.completed"],
  "secret": "your_webhook_signing_secret"
}

Full registerWebhook reference →

Supported events

payment.completed Crypto received, confirmations met, Naira payout initiated or completed

payment.failed Payment expired, underpaid, or could not be finalized

transaction.completed On-chain or ledger transaction reached final state

Payload delivery

Bitmessa sends an HTTP POST to your registered URL with a JSON body containing the event type and resource data. Your endpoint should:

Respond with 200 OK within 10 seconds
Be idempotent — the same event may be delivered more than once
Verify the payload signature using your webhook secret
Use HTTPS endpoints only in production

Signature verification

Verify incoming webhooks by computing an HMAC-SHA256 of the raw request body with your secret, then comparing to the signature header Bitmessa sends.

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Example payload

{
  "event": "payment.completed",
  "timestamp": "2025-07-08T12:00:00Z",
  "data": {
    "id": "payment_abc123",
    "status": "completed",
    "currency": "BTC",
    "amount": 0.001,
    "ngn_amount": 1372
  }
}