Webhooks

Webhook subscription management

Get webhook subscription

get

/api/v1/

/webhooks/subscribe/{tenantId}

Retrieve webhook subscription configuration for a tenant. Returns the registered webhook URL and retry attempt settings for receiving transaction status update notifications.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

tenantIdstringRequired

Responses

200

Successfully retrieved webhook subscription details

application/json

get

/webhooks/subscribe/{tenantId}

HTTPcURLJavaScriptPython

GET /api/v1/webhooks/subscribe/{tenantId} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*

200

Successfully retrieved webhook subscription details

{
  "tenant_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "webhook_url": "https://example.com/webhooks/transaction-status",
  "retry_attempts": 3,
  "is_active": true,
  "created_at": "2025-10-01T08:00:00.000Z",
  "updated_at": "2025-11-10T12:00:00.000Z"
}

Create webhook subscription

post

/api/v1/

/webhooks/subscribe/{tenantId}

Register a webhook URL to receive real-time transaction status update notifications. Configure the number of retry attempts for failed webhook deliveries. The system will POST transaction status updates to the registered URL whenever a transaction status changes.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

tenantIdstringRequired

Body

application/json

webhook_urlstring · uri · min: 1Required

retry_attemptsintegerRequired

Responses

201

Webhook subscription created successfully

application/json

400

Bad request - Invalid webhook URL or configuration

401

Unauthorized - Invalid or missing API key

409

Conflict - Webhook subscription already exists

500

Internal server error

post

/webhooks/subscribe/{tenantId}

HTTPcURLJavaScriptPython

POST /api/v1/webhooks/subscribe/{tenantId} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "webhook_url": "https://example.com",
  "retry_attempts": 1
}

{
  "tenant_id": "text",
  "webhook_url": "https://example.com",
  "retry_attempts": 1
}

Update webhook subscription

put

/api/v1/

/webhooks/subscribe/{tenantId}

Update webhook subscription configuration for a tenant. Modify the registered webhook URL and/or the number of retry attempts for failed deliveries. Returns 404 if no subscription exists.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

tenantIdstringRequired

Body

application/json

webhook_urlstring · uri · min: 1Required

retry_attemptsintegerRequired

Responses

200

Webhook subscription updated successfully

application/json

400

Bad request - Invalid webhook URL or configuration

401

Unauthorized - Invalid or missing API key

404

Not found - Webhook subscription does not exist

500

Internal server error

put

/webhooks/subscribe/{tenantId}

HTTPcURLJavaScriptPython

PUT /api/v1/webhooks/subscribe/{tenantId} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "webhook_url": "https://example.com",
  "retry_attempts": 1
}

{
  "tenant_id": "text",
  "webhook_url": "https://example.com",
  "retry_attempts": 1
}

Delete webhook subscription

delete

/api/v1/

/webhooks/subscribe/{tenantId}

Remove webhook subscription for a tenant. After deletion, the tenant will no longer receive transaction status update notifications. Returns 404 if no subscription exists.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

tenantIdstringRequired

Responses

200

Webhook subscription deleted successfully

No content

401

Unauthorized - Invalid or missing API key

404

Not found - Webhook subscription does not exist

500

Internal server error

delete

/webhooks/subscribe/{tenantId}

HTTPcURLJavaScriptPython

DELETE /api/v1/webhooks/subscribe/{tenantId} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*

No content

Transaction status update notification

Webhook sent to subscribed tenant URL when a transaction status changes

Payload

application/json

transaction_idstringRequired

Unique identifier for the transaction

statusstringRequired

Current status of the transaction

updated_atstring · date-timeRequired

Timestamp when the status was updated

tenant_idstringRequired

Unique identifier for the tenant

sender_idstringOptional

beneficiary_idstringOptional

corridor_idstringOptional

payout_method_idstringOptional

Responses

200

Webhook received and processed successfully

No content

400

Invalid webhook payload

500

Internal server error processing webhook

Payload

{
  "transaction_id": "text",
  "status": "text",
  "updated_at": "2025-12-12T09:24:03.472Z",
  "tenant_id": "text",
  "sender_id": "text",
  "beneficiary_id": "text",
  "corridor_id": "text",
  "payout_method_id": "text"
}