Webhook Endpoints API — register event destinations

Webhook endpoints are the URLs on your server that Dubu sends event notifications to. When something significant happens in your account — a deposit settles, a customer completes KYC, or a checkout payment is received — Dubu POSTs a signed JSON payload to every active endpoint subscribed to that event type. This page covers how to register and manage your endpoints. For the full list of event types and their payloads, see Webhook event types and payload reference. All routes require authentication via API key or JWT bearer token.

Endpoint object

string

Unique endpoint identifier (UUID).

url

string

The HTTPS URL Dubu delivers events to.

events

array

List of event type strings this endpoint is subscribed to. An empty array means all events are delivered.

is_active

boolean

Whether this endpoint is currently receiving events.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

Register an endpoint

POST /webhooks/endpoints

Register a new URL to receive webhook events. Dubu returns the endpoint’s signing secret (secret) in this response — store it securely. It is only shown once and is used to verify that incoming requests genuinely originate from Dubu. See verifying signatures for how to use it.

Request body

url

string

required

The fully-qualified HTTPS URL Dubu should POST events to. Must be a valid URL.

events

array

required

Array of event type strings to subscribe to (e.g. ["deposit.settled", "checkout.payment.completed"]). Pass an empty array [] to subscribe to all events.

Example

curl -X POST https://api.dubupay.com/api/v1/webhooks/endpoints \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks/dubu",
    "events": ["deposit.settled", "deposit.failed", "checkout.payment.completed"]
  }'

Response

Returns 201 Created. The secret field is only present in this response.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://yourserver.com/webhooks/dubu",
    "events": ["deposit.settled", "deposit.failed", "checkout.payment.completed"],
    "is_active": true,
    "created_at": "2024-01-15T10:00:00.000Z",
    "secret": "whsec_Abc123XYZ..."
  }
}

List endpoints

GET /webhooks/endpoints

Returns all registered webhook endpoints for your account. The secret field is never returned in list or get responses — rotate the secret if you need to retrieve it again.

Example

curl https://api.dubupay.com/api/v1/webhooks/endpoints \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

Update an endpoint

PATCH /webhooks/endpoints/:id

Update the URL, subscribed events, or active status of an endpoint.

string

required

UUID of the endpoint to update.

url

string

New delivery URL.

events

array

Updated list of event type strings. Replaces the current subscription list.

is_active

boolean

Set to false to pause delivery without deleting the endpoint.

Example

curl -X PATCH https://api.dubupay.com/api/v1/webhooks/endpoints/endpoint_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Delete an endpoint

DELETE /webhooks/endpoints/:id

Permanently removes a webhook endpoint. Dubu will stop delivering events to this URL immediately.

string

required

UUID of the endpoint to delete.

curl -X DELETE https://api.dubupay.com/api/v1/webhooks/endpoints/endpoint_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

Send a test event

POST /webhooks/endpoints/:id/test

Triggers an immediate test delivery to the endpoint. Dubu sends a signed payload to your URL so you can verify that your server receives and processes events correctly without waiting for a real event.

string

required

UUID of the endpoint to test.

curl -X POST https://api.dubupay.com/api/v1/webhooks/endpoints/endpoint_uuid_here/test \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

The response includes the payload that was sent and whether the delivery succeeded.

{
  "success": true,
  "data": {
    "success": true,
    "status": 200,
    "payload": {
      "event": "test.webhook",
      "data": {
        "message": "This is a test webhook from Dubu API.",
        "endpoint_id": "endpoint_uuid_here",
        "timestamp": "2024-01-15T10:00:00.000Z"
      },
      "timestamp": "2024-01-15T10:00:00.000Z",
      "_test": true
    }
  }
}

Rotate signing secret

POST /webhooks/endpoints/:id/rotate-secret

Generates a new signing secret for an endpoint. After rotating, you must update your server to use the new secret for signature verification. The previous secret stops working immediately.

string

required

UUID of the endpoint whose secret you want to rotate.

curl -X POST https://api.dubupay.com/api/v1/webhooks/endpoints/endpoint_uuid_here/rotate-secret \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": "endpoint_uuid_here",
    "secret": "whsec_NewSecret123..."
  }
}

View delivery logs

GET /webhooks/logs

Returns a paginated log of all webhook delivery attempts for your account, including the payload sent, the HTTP status code returned by your server, and whether delivery was considered successful.

Query parameters

endpoint_id

string

Filter logs to a specific endpoint.

event

string

Filter by event type, e.g. deposit.settled.

success

string

true to see only successful deliveries, false to see only failed ones.

page

number

Page number (1-indexed).

limit

number

Results per page. Maximum 100. Defaults to 50.

Example

curl "https://api.dubupay.com/api/v1/webhooks/logs?success=false&limit=20" \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

Log entry fields

string

Log entry UUID.

endpoint_id

string

UUID of the endpoint this delivery was attempted to.

endpoint_url

string

URL of the endpoint at the time of delivery.

event

string

The event type that was delivered.

payload

object

The full JSON payload that was sent to your endpoint.

status_code

number

HTTP status code returned by your server. 0 if the connection failed.

success

boolean

true if your server responded with a 2xx status code.

error

string

Error description if delivery failed. null on success.

created_at

string

ISO 8601 timestamp of the delivery attempt.

Overview

Auth

Payments

Trading

Commerce

Webhooks

Webhook Endpoints API — register event destinations

Endpoint object

Register an endpoint

Request body

Example

Response

List endpoints

Example

Update an endpoint

Example

Delete an endpoint

Send a test event

Rotate signing secret

View delivery logs

Query parameters

Example

Log entry fields

​Endpoint object

​Register an endpoint

​Request body

​Example

​Response

​List endpoints

​Example

​Update an endpoint

​Example

​Delete an endpoint

​Send a test event

​Rotate signing secret

​View delivery logs

​Query parameters

​Example

​Log entry fields

Endpoint object

Register an endpoint

Request body

Example

Response

List endpoints

Example

Update an endpoint

Example

Delete an endpoint

Send a test event

Rotate signing secret

View delivery logs

Query parameters

Example

Log entry fields