Incoming Events

Overview

In the previous section, we learned how to work with webhook endpoints step by step. Once you've subscribed to the events, we start sending you an HTTP POST with a JSON payload.

The common structure of the webhook looks like

{
  "type": "transfer.status_changed",
  "data": { ..... }
}

The full object is included in the data field of the JSON payload. In the example above, the event transfer.status_changed will include the whole transfer object. The same rule applied to all webhook events.

{
  "type": "transfer.status_changed",
  "data": {
    "id": "tf_XYZ123456789",
    "ownerId": "acct_98765ABCDE",
    "status": "payment_processed",
    "source": {
      "amount": "150.00",
      "fee": "2.50",
      "currency": "USDC",
      "rail": "polygon"
    },
    "destination": {
      "amount": "147.50",
      "fee": "2.50",
      "currency": "USD",
      "rail": "ach",
      "id": "rcp_QWERTY98765",
      "label": "Test Recipient",
      "details": {
        "accountName": "Demo Account",
        "accountNumber": "123456789",
        "bankName": "Example Bank",
        "routingNumber": "110000000",
        "schema": "bank_us"
      }
    },
    "fxRate": 1,
    "createdAt": "2025-09-22T12:00:00Z",
    "expiresAt": "2025-09-22T12:05:00Z"
  }
}

After receiving an event, fetch the object by its identifier to confirm it belongs to your account and to retrieve the latest state. Example:

curl -X GET "https://api.due.network/v1/transfers/tf_XYZ123456789" \
  -H "Authorization: Bearer <token>" \
  -H "Due-Account-Id: acct_98765ABCDE"