Webhooks

​

Overview

• One webhook URL per business — you can register a single HTTPS endpoint; we send payout status events and wallet movement events for your business to that URL.
• Optional signing — you can provide a secret when registering; we then sign each request so you can verify it came from Yala. We strongly recommend setting a secret and verifying the signature to protect your endpoint against spoofed webhooks.
• Use the same API key (and base URL) as for the rest of the Payout API when managing your webhook subscription.

​

Subscribe via API

​

Register a webhook URL

POST /v1/payout-api/webhooks HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <YOUR_API_KEY>

{
  "url": "https://your-server.com/webhooks/payout",
  "secret": "whsec_your_secret_for_signing"
}

​

Payload we send

• Content-Type: application/json
• Body: JSON object with the shape below.
• Headers we add:
  • X-Yala-Delivery-Id — unique ID for this delivery (use it to deduplicate if you receive the same event more than once).
  • X-Yala-Signature — only present if you set a secret; format sha256=<hex>. See Verifying the signature.

​

Payload shape

{
  "eventType": "payout.status.changed",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "occurredAt": "2025-02-10T12:00:00.000Z",
  "data": {
    "payoutId": "payout-uuid",
    "businessId": "business-uuid",
    "oldStatus": "PENDING",
    "newStatus": "PROCESSING",
    "changedAt": "2025-02-10T12:00:00.000Z",
    "reason": "Approved for processing"
  }
}

​

Wallet credit and debit

​

Event names (eventType)

​

Direction (transactionType)

​

Example payload (wallet)

{
  "eventType": "wallet.credited",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "occurredAt": "2025-02-10T12:00:00.000Z",
  "data": {
    "businessId": "business-uuid",
    "amount": 1000.0,
    "currency": "USD",
    "transactionId": "transaction-uuid",
    "createdAt": "2025-02-10T12:00:00.000Z",
    "transactionType": "cr",
    "reference": "REF-123",
    "narration": "wallet top up resolution - funding",
    "balance": 5000.0,
    "totalBalance": 5200.0
  }
}

​

Wallet data fields

​

Verifying the signature

X-Yala-Signature: sha256=a1b2c3...

1. Read the raw request body (do not parse and re-serialize; use the exact bytes received).
2. Compute HMAC-SHA256(rawBody, yourSecret).
3. Hex-encode the result.
4. Compare with the value in X-Yala-Signature after the sha256= prefix.

​

Best practices

• Respond quickly — Return HTTP 2xx as soon as you have accepted the payload. Process the event asynchronously if needed so we don’t time out.
• Deduplicate — Store deliveryId and ignore requests you have already processed so duplicate deliveries do not trigger duplicate actions.
• Set a secret and verify the signature — We strongly recommend setting a secret when registering and always verifying X-Yala-Signature before trusting the payload. Without this, your endpoint could accept spoofed webhooks from third parties.
• Use HTTPS only — We only send to HTTPS URLs. Keep your endpoint and secret secure.

​

Delivery retries

• Total attempts: 5
• Backoff schedule: 1 minute, 5 minutes, 15 minutes, 1 hour, 4 hours
• Stop condition: Any HTTP 2xx response marks the delivery as successful and stops retries
• Final state: After the 5th failed attempt, the delivery is marked as failed

​

Managing your subscription

• List: GET /v1/payout-api/webhooks returns your current subscription(s). The response does not include the secret.
• Update: PATCH /v1/payout-api/webhooks/:id with url, secret, eventTypes, or isActive as needed.
• Remove: DELETE /v1/payout-api/webhooks/:id stops notifications to that URL.