Webhook Endpoints

Configure webhook endpoints to receive real-time event notifications.

Create Webhook Endpoint

Endpoint: POST /v1/webhook_endpoints

Authentication: Required

Request Body:

Field	Type	Required	Description
`url`	string	Yes	Webhook endpoint URL (must be HTTPS)
`description`	string	No	Endpoint description
`enabled_events`	array	Yes	Array of event types to receive (minimum 1)

Available Event Types:

SMS Events:

sms.sent - SMS message sent

sms.delivered - SMS message delivered

sms.failed - SMS message failed

Payment Events:

payment.succeeded - Payment completed successfully

payment.failed - Payment failed

Invoice Events:

invoice.paid - Invoice paid

invoice.payment_failed - Invoice payment failed

invoice.overdue - Invoice overdue

Subscription Events:

subscription.created - Subscription created

subscription.updated - Subscription updated

subscription.cancelled - Subscription cancelled

Payout Events:

payout.completed - Payout completed

payout.failed - Payout failed

Example:

HTTP

TypeScript

Python

Success Response (201):

{
  "data": {
    "id": "we_abc123",
    "url": "https://example.com/webhooks/jokoor",
    "description": "Production webhook endpoint",
    "api_version": "v1",
    "enabled_events": ["payment.succeeded", "invoice.paid", "sms.delivered"],
    "status": "active",
    "secret": "whsec_abc123...",
    "metadata": {},
    "consecutive_failures": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "disabled_at": null,
    "disable_reason": null,
    "created": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

WARNING

Secret Key: The webhook secret is only visible once during creation. Store it securely to verify webhook signatures. You cannot retrieve it later.

Get Webhook Endpoint

Get details of a specific webhook endpoint.

Endpoint: GET /v1/webhook_endpoints/{id}

Authentication: Required

List Webhook Endpoints

Get a paginated list of webhook endpoints.

Endpoint: GET /v1/webhook_endpoints

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)

Update Webhook Endpoint

Update an existing webhook endpoint.

Endpoint: POST /v1/webhook_endpoints/{id}

Authentication: Required

Request Body:

Field	Type	Required	Description
`url`	string	No	Webhook endpoint URL
`description`	string	No	Endpoint description
`enabled_events`	array	No	Array of event types to receive
`status`	string	No	Endpoint status (`active`, `inactive`)
`metadata`	object	No	Custom metadata (key-value pairs)

Delete Webhook Endpoint

Delete a webhook endpoint.

Endpoint: DELETE /v1/webhook_endpoints/{id}

Authentication: Required

Success Response (204): No content

Test Webhook Endpoint

Send a test event to a webhook endpoint.

Endpoint: POST /v1/webhook_endpoints/{id}/test

Authentication: Required

Example:

HTTP

TypeScript

Python

Webhook Payload Example

When an event occurs, Jokoor sends a POST request to your webhook URL with the following structure:

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created_at": "2024-01-15T10:30:00Z",
  "livemode": false,
  "data": {
    "object": {
      "id": "txn_abc123",
      "amount": "100.00",
      "currency": "GMD",
      "status": "completed",
      "customer_email": "customer@example.com"
    }
  }
}

Verifying Webhook Signatures

Use the webhook secret to verify that requests are genuinely from Jokoor:

TypeScript

Python

Webhook Endpoints

Create Webhook Endpoint#

Get Webhook Endpoint#

List Webhook Endpoints#

Update Webhook Endpoint#

Delete Webhook Endpoint#

Test Webhook Endpoint#

Webhook Payload Example#

Verifying Webhook Signatures#

Create Webhook Endpoint

Get Webhook Endpoint

List Webhook Endpoints

Update Webhook Endpoint

Delete Webhook Endpoint

Test Webhook Endpoint

Webhook Payload Example

Verifying Webhook Signatures