Webhooks Overview - HOST Pay API

Upgrade notice: webhook safeguards

API release 0.11.0 introduces the following webhook security requirements. Ensure your integration meets them:

Live deliveries require HTTPS with a valid certificate for your endpoint’s hostname. Public HTTP endpoints are supported only for sandbox events.
Redirects are no longer followed, including HTTP-to-HTTPS and trailing-slash redirects. Set target_url to the final URL that directly accepts a POST and returns a 2xx response. You can change it using Update subscription.
Destinations must resolve only to public addresses at delivery time. Private, loopback, link-local, shared, reserved and multicast addresses are blocked. A mixed public/private DNS answer is rejected. URL credentials and fragments are not supported. Use a public HTTPS tunnel for local testing.
Unsigned fallback is removed. Missing, inactive or unreadable signing secrets prevent the HTTP request. Keep verifying signatures; do not disable verification to work around a delivery error. See Security.
Delivery-status consumers must accept processing alongside pending, delivered, failed and dead. Delivery responses now include the optional, nullable processing_started_at timestamp. Update strict response validators to accept this additive field.
Manual dispatch rejects inactive subscriptions with HTTP 409. Delivered and dead deliveries remain final; manual dispatch is not a way to revive them.

The event payload format, X-Webhook-Version, signature algorithm and delivery-ID headers are unchanged by this release. You do not need to hash your API keys or webhook signing secret, change your payload version, or rotate a working secret just for this upgrade. Clients already using direct public HTTPS endpoints and valid signature verification generally need no receiver-code changes. Before going live, run a sandbox flow, confirm a 2xx delivery, verify the signature over the raw body, and confirm duplicate deliveries do not repeat your business operation. See Testing webhooks.

Delivery concurrency and ordering

API release 0.14.0 sends automatic webhooks in parallel. Each sweep selects at most 50 deliveries and shares four concurrent senders per worker process, including across overlapping sweeps. More worker processes increase overall concurrency. Manual dispatch and retries can also overlap; this is not an ordering or exactly-once guarantee. Your receiver must accept concurrent requests and out-of-order events. Do not rely on the order of HTTP arrival to decide the latest transaction state or overwrite a final state with an older notification. Use event-specific state guards or retrieve the current transaction state when needed. Deduplicate X-HostPay-Delivery-Id (also supplied as Idempotency-Key) atomically, for example with a database unique constraint and the business update in the same transaction. A read-then-write check alone can process simultaneous duplicates twice. Payloads, signatures, delivery IDs and the ten-attempt retry policy are unchanged; exactly-once or ordered HTTP delivery is not guaranteed. Manual dispatch can return HTTP 409 if another sender recovered its claim while the request waited. Inspect the current Delivery Log before trying again; do not create another payment to recover a notification.

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.

X-Webhook-Version identifies the payload version, not the event type. Do not assume every payload has a top-level event field; use the documented payload for the events you subscribe to.

Request Headers

Every webhook delivery includes these headers:

Header	Description
`X-HostPay-Signature`	HMAC-SHA256 signature of the payload (format: `v1=<hex>`)
`X-Webhook-Timestamp`	Unix timestamp (seconds) when the webhook was sent
`X-Webhook-Version`	API version string (e.g., `2025-01`)
`X-Webhook-Source`	Always `HostPay`
`X-HostPay-Delivery-Id`	Unique delivery ID for idempotency tracking
`Idempotency-Key`	Same as `X-HostPay-Delivery-Id`

Setting Up Webhooks

Create Endpoint

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

Configure in Dashboard

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

Store Your Secret

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

Verify Signatures

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

Test

Run a sandbox payment or payout and confirm your endpoint receives the subscribed event — see Testing

Best Practices

Respond Quickly — Process Async

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.

Handle Duplicates (Idempotency)

The same delivery may arrive more than once. Use X-HostPay-Delivery-Id or Idempotency-Key to deduplicate it. Do not deduplicate solely on a transaction ID, because separate state-change events may refer to the same transaction.

Validate Timestamps

Check that X-Webhook-Timestamp is within 5 minutes of your server time to prevent replay attacks. Reject requests that are too old.

Use HTTPS Only

Live events require HTTPS. Sandbox events may use public HTTP endpoints, but HTTPS is recommended for both. Redirects are not followed.

Monitor Failures

Track failed deliveries in your logs and set up alerts. After all retry attempts are exhausted, no further automatic retries will occur.

Test in Test Mode First

Use a Test Mode payment or payout 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 total delivery attempts, including the initial attempt, not 10 additional retries.
Exponential backoff: starts at 60 seconds, doubles between attempts, adds up to 60 seconds of jitter, and caps at 30 minutes. Worker availability can delay an attempt further.
Signing and destination-validation failures also consume an attempt, even though no HTTP request is sent. An empty HTTP code means no endpoint response was recorded, not necessarily that no request reached the endpoint.
failed means a retry can be scheduled. After exhaustion, the delivery becomes dead (shown as Stopped in the dashboard) and no automatic retries occur.

Use the Delivery Log to inspect attempts, errors and the next retry time. Correct the endpoint or signing configuration before retrying. Do not recreate a payment to recover a missing webhook notification.

Next Steps

Webhook Events

Browse every event type and subscription pattern

Security

Verify signatures before processing events

Testing

Validate your endpoint before going live

​Upgrade notice: webhook safeguards

​Delivery concurrency and ordering

​What are Webhooks?

​Common Use Cases

Payment Confirmation

Transfer Updates

Payout Status

Balance Changes

​Webhook Events

​Webhook Payload

​Request Headers

​Setting Up Webhooks

​Best Practices

​Retry Policy

​Next Steps

Webhook Events

Security

Testing

Upgrade notice: webhook safeguards

Delivery concurrency and ordering

What are Webhooks?

Common Use Cases

Webhook Events

Webhook Payload

Request Headers

Setting Up Webhooks

Best Practices

Retry Policy

Next Steps