Webhook Setup

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

POST /v1/webhooks/endpoints

Request Body

string

required

The HTTPS URL where webhook payloads will be delivered. Must be publicly accessible.Example: "https://api.yourcompany.com/webhooks/payments"

string[]

required

Array of event types to subscribe to.Values: payment.completed, payment.failed, payment.cancelled, payment.timeout

string

Human-readable description for this endpoint.Example: "Production payment notifications"

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"
  }'

async function createWebhookEndpoint() {
  const path = '/v1/webhooks/endpoints';
  const body = {
    url: 'https://api.yourcompany.com/webhooks/payments',
    events: ['payment.completed', 'payment.failed'],
    description: 'Production notifications'
  };
  const headers = generateAuthHeaders('POST', path, body);

  const response = await fetch(`${BASE_URL}${path}`, {
    method: 'POST',
    headers,
    body: JSON.stringify(body)
  });

  const data = await response.json();
  // Store data.secret securely for signature verification
  return data;
}

def create_webhook_endpoint():
    path = '/v1/webhooks/endpoints'
    body = {
        'url': 'https://api.yourcompany.com/webhooks/payments',
        'events': ['payment.completed', 'payment.failed'],
        'description': 'Production notifications'
    }
    headers = generate_auth_headers('POST', path, body)

    response = requests.post(f'{BASE_URL}{path}', headers=headers, json=body)
    data = response.json()
    # Store data['secret'] securely for signature verification
    return data

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>"

async function listWebhookEndpoints() {
  const path = '/v1/webhooks/endpoints';
  const headers = generateAuthHeaders('GET', path);

  const response = await fetch(`${BASE_URL}${path}`, {
    method: 'GET',
    headers
  });

  return response.json();
}

def list_webhook_endpoints():
    path = '/v1/webhooks/endpoints'
    headers = generate_auth_headers('GET', path)

    response = requests.get(f'{BASE_URL}{path}', headers=headers)
    return response.json()

Get Endpoint

Retrieve a specific webhook endpoint by ID.

GET /v1/webhooks/endpoints/{endpointId}

Path Parameters

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

string

required

The unique identifier of the webhook endpoint.

Request Body

string

Updated HTTPS URL for webhook delivery. A validation ping is sent to verify the new URL.

string[]

Updated array of event types to subscribe to.

string

Updated description for this endpoint.

string

Endpoint status. Set to disabled to pause webhook delivery without deleting the endpoint.Values: active, disabled

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"
  }'

async function updateWebhookEndpoint(endpointId, updates) {
  const path = `/v1/webhooks/endpoints/${endpointId}`;
  const headers = generateAuthHeaders('PUT', path, updates);

  const response = await fetch(`${BASE_URL}${path}`, {
    method: 'PUT',
    headers,
    body: JSON.stringify(updates)
  });

  return response.json();
}

// Usage
await updateWebhookEndpoint('wh_01HQ3K4M5N6P7R8S9T0UVWXYZ', {
  events: ['payment.completed', 'payment.failed'],
  status: 'active'
});

def update_webhook_endpoint(endpoint_id: str, updates: dict):
    path = f'/v1/webhooks/endpoints/{endpoint_id}'
    headers = generate_auth_headers('PUT', path, updates)

    response = requests.put(f'{BASE_URL}{path}', headers=headers, json=updates)
    return response.json()

# Usage
update_webhook_endpoint('wh_01HQ3K4M5N6P7R8S9T0UVWXYZ', {
    'events': ['payment.completed', 'payment.failed'],
    'status': 'active'
})

Delete Endpoint

Remove a webhook endpoint. This action is permanent.

DELETE /v1/webhooks/endpoints/{endpointId}

Path Parameters

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>"

async function deleteWebhookEndpoint(endpointId) {
  const path = `/v1/webhooks/endpoints/${endpointId}`;
  const headers = generateAuthHeaders('DELETE', path);

  const response = await fetch(`${BASE_URL}${path}`, {
    method: 'DELETE',
    headers
  });

  return response.status === 204;
}

def delete_webhook_endpoint(endpoint_id: str):
    path = f'/v1/webhooks/endpoints/{endpoint_id}'
    headers = generate_auth_headers('DELETE', path)

    response = requests.delete(f'{BASE_URL}{path}', headers=headers)
    return response.status_code == 204

Error Codes

Code	HTTP Status	Description
`WEBHOOKS_NOT_CONFIGURED`	400	Webhooks feature is not enabled for your group
`ENDPOINT_LIMIT_REACHED`	400	Maximum of 16 endpoints per group reached
`INVALID_ENDPOINT_URL`	400	URL must use HTTPS protocol
`ENDPOINT_PING_FAILED`	400	Validation ping to endpoint URL failed
`INVALID_EVENT_TYPE`	400	Unknown event type in events array
`ENDPOINT_NOT_FOUND`	404	Webhook 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

QR API

Onboarding API

Terminal Gateway

Transaction Reporting API

Ecom API

Shared Resources

Overview

Endpoint Limits

Managing Webhook Endpoints

Create Endpoint

Request Body

Request Example

Response (201 Created)

Code Example

List Endpoints

Response (200 OK)

Code Example

Get Endpoint

Path Parameters

Response (200 OK)

Update Endpoint

Path Parameters

Request Body

Request Example

Response (200 OK)

Code Example

Delete Endpoint

Path Parameters

Response (204 No Content)

Code Example

Error Codes

Next Steps

Receiving Webhooks

HTTP Endpoints

Authentication

Data Types

​Overview

​Endpoint Limits

​Managing Webhook Endpoints

​Create Endpoint

​Request Body

​Request Example

​Response (201 Created)

​Code Example

​List Endpoints

​Response (200 OK)

​Code Example

​Get Endpoint

​Path Parameters

​Response (200 OK)

​Update Endpoint

​Path Parameters

​Request Body

​Request Example

​Response (200 OK)

​Code Example

​Delete Endpoint

​Path Parameters

​Response (204 No Content)

​Code Example

​Error Codes

​Next Steps

Receiving Webhooks

HTTP Endpoints

Authentication

Data Types

Overview

Endpoint Limits

Managing Webhook Endpoints

Create Endpoint

Request Body

Request Example

Response (201 Created)

Code Example

List Endpoints

Response (200 OK)

Code Example

Get Endpoint

Path Parameters

Response (200 OK)

Update Endpoint

Path Parameters

Request Body

Request Example

Response (200 OK)

Code Example

Delete Endpoint

Path Parameters

Response (204 No Content)

Code Example

Error Codes

Next Steps