Skip to main content

​
What are Webhooks?

Webhooks allow your application to receive real-time notifications when events occur in HOST Pay. Instead of polling the API, HOST Pay will send HTTP POST requests to your specified endpoint whenever a transaction or account event takes place.

​
Common Use Cases

Payment Confirmation

Get notified the moment deposits are successfully processed

Transfer Updates

Track wallet-to-wallet transfers in real time

Payout Status

Monitor withdrawal processing and failures

Balance Changes

React to wallet balance and fee events as they happen

​
Webhook Events

HOST Pay sends webhooks for payment, transfer, payout, wallet, transaction, escrow, and system events. You can subscribe to individual events or use wildcards (e.g., payment.*) to receive all events in a group. See Webhook Events for the full list of event types and subscription patterns.

​
Webhook Payload

Every webhook delivers a JSON body with this structure: 
{
  "data": {
    "id": "txn_abc123xyz",
    "wallet_id": "wallet_def456",
    "amount": 100.0,
    "currency": "USD",
    "status": "succeeded",
    "payment_method": "mobile_money",
    "reference_id": "pmc_789xyz",
    "created_at": "2025-01-16T10:25:00Z",
    "updated_at": "2025-01-16T10:30:00Z"
  },
  "metadata": {}
}
The status field inside data reflects the outcome extracted from the event type (e.g., succeeded, failed, created). The metadata object carries any additional context attached to the event.
The event type itself (payment.succeeded, payout.failed, etc.) is identified by the X-Webhook-Version and event delivery headers, not an event field in the body.

​
Request Headers

Every webhook delivery includes these headers:
HeaderDescription
X-HostPay-SignatureHMAC-SHA256 signature of the payload (format: v1=<hex>)
X-Webhook-TimestampUnix timestamp (seconds) when the webhook was sent
X-Webhook-VersionAPI version string (e.g., 2025-01)
X-Webhook-SourceAlways HostPay
X-HostPay-Delivery-IdUnique delivery ID for idempotency tracking
Idempotency-KeySame as X-HostPay-Delivery-Id

​
Setting Up Webhooks

1

Create Endpoint

Set up an HTTPS endpoint to receive POST requests (e.g., https://yourapp.com/webhooks/hostpay)
2

Configure in Dashboard

Add your webhook URL and select the events you want to subscribe to in the HOST Pay dashboard
3

Store Your Secret

Save the webhook secret displayed during setup — you’ll need it to verify signatures
4

Verify Signatures

Validate every incoming webhook’s signature before processing it — see Security
5

Test

Send a test.ping event from the dashboard and confirm your endpoint receives it — see Testing

​
Best Practices

Return a 200 OK as soon as you receive the webhook, then process it in the background. HOST Pay considers any non-2xx response a failure and will retry.
The same event may be delivered more than once. Use the X-HostPay-Delivery-Id header or data.id to detect duplicates and skip re-processing.
Check that X-Webhook-Timestamp is within 5 minutes of your server time to prevent replay attacks. Reject requests that are too old.
Your endpoint must be served over HTTPS. HTTP endpoints will not receive webhooks.
Track failed deliveries in your logs and set up alerts. After all retry attempts are exhausted, no further automatic retries will occur.
Use Test Mode and the test.ping event to validate your endpoint before processing live events.

​
Retry Policy

If your endpoint returns a non-2xx status code or times out, HOST Pay retries the delivery automatically:
  • Up to 10 retry attempts after the initial delivery failure
  • Exponential backoff: the delay between attempts doubles each time, starting at 60 seconds and capping at 30 minutes
  • After all attempts are exhausted, the delivery is marked failed and no further retries occur
You can view delivery history and manually re-trigger failed webhooks from the HOST Pay dashboard.

​
Next Steps

Webhook Events

Browse every event type and subscription pattern

Security

Verify signatures before processing events

Testing

Validate your endpoint before going live