Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
id
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.
​
id
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.
​
id
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.
​
id
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.
​
id
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

​
id
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.