Webhooks API

Base path: https://gateway.useyona.com/a/v1/organizations/:orgId/webhooks

All webhook endpoints require the organization ID in the URL path.

Create webhook

POST /a/v1/organizations/:orgId/webhooks

Request body

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive events
`events`	string[]	Yes	Events to subscribe to
`description`	string	No	Human-readable description

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.zenithsoftware.ng/webhooks/yona",
    "events": ["invoice.approved", "invoice.rejected", "invoice.submission_failed"],
    "description": "Production invoice notifications"
  }'

🚨 Store the webhook secret immediately

The secret field is returned only in the create response. Store it securely — you need it to verify webhook signatures.

List webhooks

GET /a/v1/organizations/:orgId/webhooks

bash

curl https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks \
  -H "Authorization: Bearer sk_test_your_key_here"

Get webhook

GET /a/v1/organizations/:orgId/webhooks/:id

bash

curl https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/wh_6f7a8b9c-0d1e-2345-6789-0abcdef12345 \
  -H "Authorization: Bearer sk_test_your_key_here"

Update webhook

PATCH /a/v1/organizations/:orgId/webhooks/:id

bash

curl -X PATCH https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/wh_6f7a8b9c-0d1e-2345-6789-0abcdef12345 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["invoice.approved", "invoice.rejected", "invoice.submission_failed", "invoice.cancelled"]
  }'

Delete webhook

DELETE /a/v1/organizations/:orgId/webhooks/:id

bash

curl -X DELETE https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/wh_6f7a8b9c-0d1e-2345-6789-0abcdef12345 \
  -H "Authorization: Bearer sk_test_your_key_here"

Test webhook

POST /a/v1/organizations/:orgId/webhooks/:id/test

Send a test event to verify your endpoint is reachable and correctly verifying signatures.

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/wh_6f7a8b9c-0d1e-2345-6789-0abcdef12345/test \
  -H "Authorization: Bearer sk_test_your_key_here"

List deliveries

GET /a/v1/organizations/:orgId/webhooks/:webhookId/deliveries

Get delivery history for a webhook endpoint.

bash

curl https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/wh_6f7a8b9c-0d1e-2345-6789-0abcdef12345/deliveries \
  -H "Authorization: Bearer sk_test_your_key_here"

Retry delivery

POST /a/v1/organizations/:orgId/webhooks/deliveries/:deliveryId/retry

Retry a failed webhook delivery.

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/deliveries/del_8b9c0d1e-2f3a-4567-8901-bcdef1234567/retry \
  -H "Authorization: Bearer sk_test_your_key_here"

Webhook payload shape

Every webhook delivery sends this JSON structure:


{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "invoice.approved",
  "environment": "sandbox",
  "timestamp": "2026-04-30T11:10:05.000Z",
  "data": {
    "invoiceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invoiceNumber": "INV-2026-001",
    "status": "accepted",
    "jurisdiction": "NG",
    "authorityReference": "NRS-REF-001",
    "submittedAt": "2026-04-30T11:10:05.000Z"
  }
}

Signature verification

Every delivery includes an HMAC-SHA256 signature in the X-Webhook-Signature header. See Core Concepts — Webhooks for verification implementation.

Retry logic

3 total attempts (1 initial + 2 retries) with exponential backoff
Success = HTTP 2xx response
Timeout = 10 seconds per attempt