Introduction to Webhooks
How HellOOpass delivers bill/order events to your server in real time.
Webhook contract
Event names are final (placed, confirmed, rejected, success). The signature header and payload fields remain illustrative until the full webhook specification is published.
HellOOpass sends an HTTP POST to your server whenever a bill/order event occurs, so your app learns outcomes in real time instead of polling for them.
Push vs poll
| Approach | How it works | Trade-off |
|---|---|---|
| Webhooks (push) | HellOOpass POSTs to your endpoint as events happen. | Needs a public HTTPS endpoint that responds fast. |
| Polling | Your server repeatedly calls the API for status. | Adds latency and can hit rate limits. |
Use webhooks for delivery, and confirm with Verify Payment when your risk policy requires it.
Guarantees
- At-least-once delivery — the same event may arrive more than once, including after timeouts or non-
2xxresponses. - Verify signatures — authenticate every request with
X-HellOOpass-Signaturebefore trusting it. - Process idempotently — dedupe by event id so redeliveries never cause double effects.
What you receive
| Piece | Example |
|---|---|
| Event type | success |
| Signature header | X-HellOOpass-Signature |
| Event id | evt_01HZX9K2EXAMPLE |
| Your endpoint | https://your-app.com/webhooks/helloopass |
Next steps
Configure your endpoint
Create a public HTTPS endpoint and subscribe to events (Configuring a Webhook Endpoint).
Verify signatures
Check the signature header on every delivery before you process anything.
Handle duplicates
Design for redelivery from day one — persist first, then return 200 OK.