Skip to main content

​
Overview

Webhooks provide an asynchronous alternative to the 90-second long-polling model used by the standard payment endpoint. Instead of waiting for a terminal response, you can receive payment results via HTTP callbacks to your server. When to use webhooks:
  • Your integration cannot handle 90-second HTTP timeouts
  • You prefer event-driven architecture
  • You need to process payments asynchronously
Endpoint URLs must be publicly reachable. When you create an endpoint, the system sends a validation ping to verify connectivity. Endpoints that fail this ping test cannot be created.

​
Endpoint Limits

Each group can configure up to 16 webhook endpoints. This limit applies across all event type subscriptions.

​
Managing Webhook Endpoints

​
Create Endpoint

Register a new webhook endpoint to receive payment notifications. 
POST /v1/webhooks/endpoints

​
Request Body

​
url
string
required
The HTTPS URL where webhook payloads will be delivered. Must be publicly accessible.Example: "https://api.yourcompany.com/webhooks/payments"
​
events
string[]
required
Array of event types to subscribe to.Values: payment.completed, payment.failed, payment.cancelled, payment.timeout
​
description
string
Human-readable description for this endpoint.Example: "Production payment notifications"
​
metadata
object
Custom key-value pairs to associate with this endpoint.

​
Request Example

{
  "url": "https://api.yourcompany.com/webhooks/payments",
  "events": ["payment.completed", "payment.failed", "payment.cancelled", "payment.timeout"],
  "description": "Production payment notifications",
  "metadata": {
    "environment": "production"
  }
}

​
Response (201 Created)

{
  "endpointId": "wh_01HQ3K4M5N6P7R8S9T0UVWXYZ",
  "url": "https://api.yourcompany.com/webhooks/payments",
  "events": ["payment.completed", "payment.failed", "payment.cancelled", "payment.timeout"],
  "description": "Production payment notifications",
  "secret": "whsec_abc123xyz789...",
  "status": "active",
  "metadata": {
    "environment": "production"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
The secret is only returned when creating the endpoint. Store it securely for signature verification. You cannot retrieve it later.

​
Code Example

curl -X POST "https://{your-api-endpoint}/v1/webhooks/endpoints" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -H "x-timestamp: 2024-01-15T10:30:00.000Z" \
  -H "x-signature: <computed-signature>" \
  -d '{
    "url": "https://api.yourcompany.com/webhooks/payments",
    "events": ["payment.completed", "payment.failed"],
    "description": "Production notifications"
  }'

​
List Endpoints

Retrieve all webhook endpoints for your group. 
GET /v1/webhooks/endpoints

​
Response (200 OK)

{
  "endpoints": [
    {
      "endpointId": "wh_01HQ3K4M5N6P7R8S9T0UVWXYZ",
      "url": "https://api.yourcompany.com/webhooks/payments",
      "events": ["payment.completed", "payment.failed", "payment.cancelled", "payment.timeout"],
      "description": "Production payment notifications",
      "status": "active",
      "metadata": {
        "environment": "production"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "count": 1,
  "timestamp": "2024-01-15T10:35:00.000Z"
}

​
Code Example

curl -X GET "https://{your-api-endpoint}/v1/webhooks/endpoints" \
  -H "x-api-key: your-api-key" \
  -H "x-timestamp: 2024-01-15T10:35:00.000Z" \
  -H "x-signature: <computed-signature>"

​
Get Endpoint

Retrieve a specific webhook endpoint by ID. 
GET /v1/webhooks/endpoints/{endpointId}

​
Path Parameters

​
endpointId
string
required
The unique identifier of the webhook endpoint.

​
Response (200 OK)

{
  "endpointId": "wh_01HQ3K4M5N6P7R8S9T0UVWXYZ",
  "url": "https://api.yourcompany.com/webhooks/payments",
  "events": ["payment.completed", "payment.failed", "payment.cancelled", "payment.timeout"],
  "description": "Production payment notifications",
  "status": "active",
  "metadata": {
    "environment": "production"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

​
Update Endpoint

Update an existing webhook endpoint’s configuration. 
PUT /v1/webhooks/endpoints/{endpointId}

​
Path Parameters

​
endpointId
string
required
The unique identifier of the webhook endpoint.

​
Request Body

​
url
string
Updated HTTPS URL for webhook delivery. A validation ping is sent to verify the new URL.
​
events
string[]
Updated array of event types to subscribe to.
​
description
string
Updated description for this endpoint.
​
status
string
Endpoint status. Set to disabled to pause webhook delivery without deleting the endpoint.Values: active, disabled
​
metadata
object
Updated custom metadata.

​
Request Example

{
  "events": ["payment.completed", "payment.failed"],
  "status": "active"
}

​
Response (200 OK)

{
  "endpointId": "wh_01HQ3K4M5N6P7R8S9T0UVWXYZ",
  "url": "https://api.yourcompany.com/webhooks/payments",
  "events": ["payment.completed", "payment.failed"],
  "description": "Production payment notifications",
  "status": "active",
  "metadata": {
    "environment": "production"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T11:00:00.000Z"
}

​
Code Example

curl -X PUT "https://{your-api-endpoint}/v1/webhooks/endpoints/wh_01HQ3K4M5N6P7R8S9T0UVWXYZ" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -H "x-timestamp: 2024-01-15T11:00:00.000Z" \
  -H "x-signature: <computed-signature>" \
  -d '{
    "events": ["payment.completed", "payment.failed"],
    "status": "active"
  }'

​
Delete Endpoint

Remove a webhook endpoint. This action is permanent. 
DELETE /v1/webhooks/endpoints/{endpointId}

​
Path Parameters

​
endpointId
string
required
The unique identifier of the webhook endpoint.

​
Response (204 No Content)

No response body is returned on successful deletion.

​
Code Example

curl -X DELETE "https://{your-api-endpoint}/v1/webhooks/endpoints/wh_01HQ3K4M5N6P7R8S9T0UVWXYZ" \
  -H "x-api-key: your-api-key" \
  -H "x-timestamp: 2024-01-15T12:00:00.000Z" \
  -H "x-signature: <computed-signature>"

​
Error Codes

CodeHTTP StatusDescription
WEBHOOKS_NOT_CONFIGURED400Webhooks feature is not enabled for your group
ENDPOINT_LIMIT_REACHED400Maximum of 16 endpoints per group reached
INVALID_ENDPOINT_URL400URL must use HTTPS protocol
ENDPOINT_PING_FAILED400Validation ping to endpoint URL failed
INVALID_EVENT_TYPE400Unknown event type in events array
ENDPOINT_NOT_FOUND404Webhook endpoint does not exist

​
Next Steps

Receiving Webhooks

Handle webhook payloads and verify signatures

HTTP Endpoints

Use webhookMode in payment requests

Authentication

HMAC signature computation

Data Types

Webhook data type reference