Skip to content

Webhooks

We send most of our updates via webhooks.

Webhook Structure

A typical webhook payload looks like this:

  {
    "Data": {
      key: string
      "Object": "OnchainDeposit"
    },
    "CreatedAt": "2024-11-12 21:31:25.576314 +0100 WAT m=+31.505311709",
    "Event": "deposit.received"
  }

Signature Verification

Along with the webhook payload, we include an x-zip-signature header. This header contains a SHA-512 hash of the webhook body combined with your webhook secret, allowing you to verify its origin. However, we do not recommend relying solely on webhooks; you should verify the state of data using the API as well.

Events

Here are some of the events you can expect to receive:

  • deposit.received

    This event indicates that a deposit has been received. The payload looks like this:

        {
      "data": {
        "transactionid": "a025674f-53f9-4876-b1a9-9c2ff0ad6418",
        "address": "0x1D8C69d46B271cbf30c3daaaF85e4eE7a5723911",
        "addressid": "8faa9b55-a982-4811-a6bb-f44b86c21c4c",
        "token": "usdc",
        "value": 100.5,
        "txhash": "0x0090a07c7c1ada3117074cfca84cc9452b96fc6041cee5735d8c521060c2dde2",
        "chain": "ethereum",
        "object": "OnchainDeposit"
      },
      "createdat": "2024-11-12 21:31:25.576314 +0100 WAT m=+31.505311709",
      "event": "deposit.received"
    }

  • fiat_payout_complete

This event indicates that a fiat payout has been successfully completed.

    {
      "data": {
        "payoutid": "payout-id-12345",
        "amount": 1000,
        "fiatamount": 1000,
        "currency": "usd",
        "payoutcurrency": "ngn",
        "reference": "ref-67890",
        "status": "completed",
        "bankcode": "123456",
        "bankaccountnumber": "0123456789"
      },
      "createdat": "2024-11-12 23:00:00.654321 +0100 WAT m=+60.654321987",
      "event": "fiat_payout_complete"
    }
  • fiat_payout_failed

This event indicates that a fiat payout has failed.

  {
    "data": {
      "payoutid": "payout-id-54321",
      "amount": 500,
      "fiatamount": 500,
      "currency": "usd",
      "payoutcurrency": "ngn",
      "reference": null,
      "status": "failed",
      "bankcode": null,
      "bankaccountnumber": null
    },
    "createdat": "2024-11-13 10:15:00.987654 +0100 WAT m=+75.987654321",
    "event": "fiat_payout_failed"
  }
  • fiat_payout_cancelled

This event indicates that a fiat payout has been cancelled.

  {
    "data": {
      "payoutid": "payout-id-cancelled123",
      "amount": 250,
      "fiatamount": 250,
      "currency": null,
      "payoutcurrency": null,
      "reference": null,
      "status": "cancelled",
      "bankcode": null
    },
    "createdat": "2024-11-13 11:00:00.000000 +0100 WAT",
    "event": "fiat_payout_cancelled"
  }
  • onchain_payout_complete

This event indicates that an on-chain payout has been successfully completed.

  {
    "data": {
      "transactionid": "onchain-payout-123",
      "address": "0x4a80ca2f0349c6c75c81916ad15304b598e795f9",
      "token": "eth",
      "amount": 1.5,
      "txhash": "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123",
      "chain": "ethereum",
      "object": "OnchainTransfer"
    },
    "createdat": "2024-11-13 12:00:00.000000 +0100 WAT",
    "event": "onchain_payout_complete"
  }
  • onchain_payout_failed

This event indicates that an on-chain payout has failed.

{
  "data": {
    "transactionid": "onchain-payout-456",
    "address": "0x7f08137d3ff5b5514c0402776ca00c0b0f4f434b",
    "token": "eth",
    "amount": 0.75,
    "txhash": null,
    "chain": "ethereum",
    "failurereason": "insufficient_funds",
    "object": "OnchainTransfer"
  },
  "createdat": "2024-11-13 13:00:00.000000 +0100 WAT",
  "event": "onchain_payout_failed"
}
  • checkout_payment_completed

This event indicates that a payment has been successfully completed via checkout.

  {
    "data": {
      "sessionid": "12345-session-id",
      "txref": "tx-ref-67890",
      "email": "user@example.com",
      "amountcredited": 500,
      "amountcharged": 510,
      "currency": "usd",
      "status": "success",
      "meta": {
        "customfield1": "value1",
        "customfield2": "value2"
      }
    },
    "createdat": "2024-11-12 22:15:00.123456 +0100 WAT m=+45.123456789",
    "event": "checkout_payment_completed"
  }