Webhooks - Portal

Overview

Due delivers lifecycle events (KYC, transfers, virtual accounts) to a URL you register. Webhooks are the recommended way to track status changes rather than checking state yourself. Unlike some integrations, Due webhook endpoints are managed through the Portal Custodian API, not a provider dashboard and not the Client API. You register a URL, subscribe to events, and verify each delivery with the endpoint’s Ed25519 public key.

These calls use a Custodian API key (Authorization: Bearer [custodian-api-key]), not a client session token. Endpoints are environment-scoped: register them separately for each environment (for example Development and Production). The shorthand paths below are relative to /api/v3/custodians/me/integrations/due.

1. List available events

GET /webhooks/events returns the event types you can subscribe to.

curl --request GET \
  --url https://api.portalhq.io/api/v3/custodians/me/integrations/due/webhooks/events \
  --header 'Authorization: Bearer [custodian-api-key]'

2. Create a webhook endpoint

POST /webhooks registers your URL. Pass the events you want in events, or omit it to receive all of them.

curl --request POST \
  --url https://api.portalhq.io/api/v3/custodians/me/integrations/due/webhooks \
  --header 'Authorization: Bearer [custodian-api-key]' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: [unique-key]' \
  --data '{
    "url": "https://example.com/webhooks/due",
    "description": "Production events",
    "events": ["transfer.status_changed", "virtual_account.updated", "bp.kyc.status_changed"]
  }'

Example response:

{
  "data": {
    "id": "whe_123",
    "url": "https://example.com/webhooks/due",
    "subscribedEvents": ["transfer.status_changed", "virtual_account.updated", "bp.kyc.status_changed"],
    "enabled": true,
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA...\n-----END PUBLIC KEY-----\n"
  }
}

Store the publicKey. It is the Ed25519 key you use to verify every delivery from this endpoint, and it is returned only in the endpoint’s create and list responses.

Event	Fires when
`transfer.created`	A transfer is created.
`transfer.status_changed`	A transfer moves through `awaiting_funds`, `funds_received`, `approved`, `payment_submitted`, `payment_processed` (and failure or refund states).
`virtual_account.created`	A virtual account is created.
`virtual_account.updated`	A virtual account changes state, including when it activates.
`bp.kyc.status_changed`	The customer’s KYC status changes.
`transfers.kyc.submission.status_changed`	A KYC submission changes state (provider-specific `sumsub` and `bridge` variants also exist).
`bp.tos_accepted`	The customer accepts a terms of service document.

transfer.status_changed tracks the same statuses shown in the payins and payouts guides, and virtual_account.updated tells you when a virtual account becomes active.

4. Receive and verify deliveries

Due sends a POST to your URL for each event, with the signature hex-encoded in the X-Webhook-Signature header. Verify it against the raw request body using the endpoint’s Ed25519 publicKey before trusting the payload.

import crypto from 'node:crypto'

function verifyDueWebhook(rawBody, signatureHex, publicKeyPem) {
  return crypto.verify(
    null,
    Buffer.from(rawBody),
    publicKeyPem,
    Buffer.from(signatureHex, 'hex'),
  )
}

// Express example. Capture the raw body (e.g. express.raw()) so the bytes match what Due signed.
app.post('/webhooks/due', express.raw({ type: '*/*' }), (req, res) => {
  const signature = req.header('X-Webhook-Signature')
  if (!signature || !verifyDueWebhook(req.body, signature, DUE_ENDPOINT_PUBLIC_KEY)) {
    return res.sendStatus(401)
  }

  res.sendStatus(200)
  const event = JSON.parse(req.body.toString('utf8'))
  processAsync(event)
})

Verify the signature over the raw, unparsed body. Reframing the JSON changes the bytes and breaks verification. Reject any delivery that fails verification.

Acknowledge deliveries quickly with a 2XX, then process events asynchronously so a slow handler does not cause Due to retry.

5. Manage endpoints

GET /webhooks lists your registered endpoints.
POST /webhooks/{webhookId} updates one; send any of url, description, events, or enabled (set enabled: false to pause deliveries without deleting).
DELETE /webhooks/{webhookId} removes one.

curl --request POST \
  --url https://api.portalhq.io/api/v3/custodians/me/integrations/due/webhooks/whe_123 \
  --header 'Authorization: Bearer [custodian-api-key]' \
  --header 'Content-Type: application/json' \
  --data '{ "enabled": false }'

6. Inspect and retry deliveries

GET /webhooks/{webhookId}/events returns the delivery history for an endpoint, including attempts, responseStatusCode, and lastError. Retry a specific event with POST /webhooks/{webhookId}/events/{eventId}/retry.

curl --request GET \
  --url https://api.portalhq.io/api/v3/custodians/me/integrations/due/webhooks/whe_123/events \
  --header 'Authorization: Bearer [custodian-api-key]'

The response is paginated: when more events exist, data.next holds the cursor for the next page. Portal forwards your query parameters to Due, so pass that value back as Due’s pagination cursor on the following request to page through the history.

In the event history, eventData is the event payload as a byte array. Decode it to JSON before reading, for example JSON.parse(Buffer.from(eventData).toString('utf8')).

​Overview

​1. List available events

​2. Create a webhook endpoint

​3. Events to subscribe to

​4. Receive and verify deliveries

​5. Manage endpoints

​6. Inspect and retry deliveries

​Next steps

Overview

1. List available events

2. Create a webhook endpoint

3. Events to subscribe to

4. Receive and verify deliveries

5. Manage endpoints

6. Inspect and retry deliveries

Next steps