Skip to main content

​
Introduction

Webhooks enable your app get notified of events and state changes when interacting with Onboard’s widget or API. For instance, you’ll receive a webhook notification when an order transitions from INITIATED to DEPOSITED.

​
Setting up a webhook

To get started, configure a publicly accessible webhook URL from Onboard Connect’s Settings in the Business portal dashboard.
This URL must be able to:
  • Return a 200 OK HTTP status code with no response body.
  • Accept the webhook payload (see structure below).
  • Verify the authenticity of the sender using the signature in the request header.
If the webhook endpoint does not specify a 200 0K HTTP response code on receipt of webhook data, there will be subsequent attempts to resend it until the retry attempts are exhausted.

Number of retry attempts is currently set at 3.

​
Verifying webhook origin

Since your webhook URL is publicly available, you need to verify that events originate from Onboard and not a bad actor. To ensure this, each webhook attempt makes use of signed HTTP headers, which contain values you can use to verify the authenticity of the data being transmitted between Onboard and your application. The following signed headers can be used:

​
x-signature

  • Here’s an example, in Javascript, of how this parameter can be verified:
const crypto = require('crypto');

function verifyWebhook(payload, signature, apiSecret) {
  const timestamp = payload.timestamp;
  const data = `t=${timestamp}&${JSON.stringify(payload.data)}`;
  const expectedSignature = crypto
    .createHmac('sha256', apiSecret)
    .update(data)
    .digest('hex');

  return expectedSignature === signature;
}
The apiSecret is the same as the one configured from your Business portal dashboard.

​
x-timestamp

  • This is the timestamp used to generate the signature

​
Webhook payload structure

A webhook payload will typically conform to the structure below: 
{
  "event" : "<WEBHOOK_EVENT>", // Name of the event triggering the webhook
  "data" : {}, // Event-specific payload data
  "timestamp" : "1674775222" // Event timestamp in Unix format
}
data is an object which is peculiar to the specific webhook context.

​
Sample payload

  {
    "event" : "order.state_transition",
    "data" : {
        "id": "76733823-b8b3-4aad-b603-0ddbccac7f57",
        "reference": "0173270620673048624933",
        "customerId": "5a83377d-7c57-4725-992f-9c50349af917",
        "customerName": "Nonami Animashaun",
        "offer": {
            "offerId": "488a550c-ee5a-4505-9f3d-774c80b7dc71",
            "partnerId": "b542a14a-ac19-4d9c-9bb8-fd7b7d7c16c2",
            "transactionType": "OFFRAMP",
            "rate": 16.32,
            "networkId": "bsc_testnet",
            "token": "USDT",
            "tokenAmount": 3,
            "fiatSymbol": "GHS",
            "fiatAmount": 48.96,
            "partnerDisplayName": "The_Merchant",
            "usdAmount": 3,
            "reservationStatus": null,
            "adNote": "",
            "fee": null,
            "channels": [

            ],
            "instantPayEnabled": false,
            "instantPayPaymentAccountId": null,
            "customPayinProvider": null,
            "tradeMode": "P2P",
            "tradeCriteria": null
        },
        "status": "AWAITING_ACCEPTANCE",
        "escrowAddress": "0xa9ba7f7ec7701aba3b70983014fe452e47ca62e2",
        "paymentChannelId": "BANK_TRANSFER_GHANA",
        "customerWallet": {
            "walletAddress": "0xe1adD9b4861BD42251683C5320d9601eE9Cf53b8",
            "networkId": "bsc_testnet",
            "walletName": null
        },
        "tokenAddress": "0x13e42c4a865b3cb4aec022c80c5fd944f3962573",
        "createdAt": "2024-11-27T13:57:56.970Z",
        "initiatedAt": null,
        "depositedAt": null,
        "confirmedAt": null,
        "completedAt": null,
        "cancelledAt": null,
        "disputeId": null,
        "lockHash": null,
        "confirmationHash": null,
        "cancellationHash": null,
        "cancellationReason": null,
        "isPartnerAcknowledged": false,
        "rating": null,
        "isCexOrder": false,
        "tradeValue": 3,
        "merchantTokenValue": 3,
        "customerTokenValue": 3,
        "payableAmount": 48.96,
        "fee": {
            "asToken": "0",
            "asFiat": 0
        },
        "instantPayProcessingStatus": null,
        "thirdpartyOrderInfo": {
            "businessId": "60037f44-9094-4bd5-a316-21995e8985c9",
            "tradeId": "c1106507-ef09-4af1-8af5-2dd4463b6327",
            "product": "WEB3",
            "blockainOrderId": null,
            "externalOrderReference": "bf27fa83-c0f6-414c-b2f8-3008c9542b05" // same as the orderId passed when initiating the order
        }
    },
    "timestamp" : "1732718962"
  }

​
Supported webhook events

EventDescription
order.state_transitionTriggered when an order’s state changes, such as from INITIATED to DEPOSITED. Includes detailed payload data for tracking.

​
Order states

StateDescriptionIs terminalAllowed transition
PENDINGThis is an order’s initial state when instantiated by a userNoAWAITING_ACCEPTANCE
INITIATED
CANCELLED
AWAITING_ACCEPTANCEFor orders that require prior acceptance before being initiated, this state indicates that the merchant is yet to accept the order.

This is usually because the merchant turned off auto-escrow on their ad, or the customer is selling an ERC-20 token.		NoCANCELLED
INITIATED
INITIATEDThe order has been create onchain, but the buyer hasn’t confirmed sending fiat to the sellerNoCANCELLED
DEPOSITED
IN_DISPUTE
DEPOSITEDThis indicates that the buyer has confirmed making a fiat transfer to the sellerNoCONFIRMED
CANCELLED
IN_DISPUTE
CONFIRMEDThe seller has confirmed receipt of fiatNoCOMPLETED
IN_DISPUTEA participant in the transaction has raised a disputeNoCANCELLED
CONFIRMED
COMPLETEDThe order has been completed and closed on chainYesN/A
CANCELLEDThe order was cancelledYesN/A
A terminal state indicates that the state/status cannot be reversed, or transition to a different state.

It usually means the order has terminated, either as completed or cancelled.