Webhook events
Catalog the 0Bit webhook event types, payload shapes, handler responsibilities, and product boundaries that public integrators can rely on.
Webhook events tell your backend that a 0Bit object changed state. Treat each event as a signed notification that should be verified, persisted, deduped, and then reconciled against your own order, account, invoice, or balance records.
The event list below is source-backed for 0Gate. 0Base and 0Pools event delivery must remain review-gated until Product and Engineering approve the live event contract for those products.
Do not fulfill from browser callbacks
Browser callbacks are UX hints. Fulfillment, balance updates, invoice status, settlement tasks, and support records must use verified server-side events or trusted API reads.
Envelope
Most product events use the same envelope shape:
| Field | Meaning | Handler use |
|---|---|---|
id | Unique event id. | Dedupe retries and replay attempts. |
type | Event type string. | Route to the correct handler. |
created_at | Event creation time. | Audit and stale-event checks. |
data | Product object or event-specific payload. | Read status, object id, metadata, and references. |
Example:
{
"id": "evt_test_123",
"type": "gate_session.completed",
"created_at": 1782475200,
"data": {
"id": "gs_test_123",
"object": "gate_session",
"status": "completed",
"metadata": {
"order_id": "order_test_123"
}
}
}Delivery headers
0Gate delivery evidence includes these headers:
| Header | Purpose |
|---|---|
Gate-Signature | HMAC signature over timestamp and raw request body. |
X-0bit-Timestamp | Timestamp used for replay-window checks. |
X-0bit-Event-Id | Event id for logging and dedupe correlation. |
X-0bit-Event-Type | Event type for delivery-level triage. |
Always verify the raw body before using the event. Do not parse and reserialize JSON before signature verification.
0Gate session events
| Event type | When it fires | Recommended action |
|---|---|---|
gate_session.created | A session has been created. | Store the session id and mark your order as pending. |
gate_session.processing | The hosted flow is in progress. | Keep the user-facing state pending and wait for terminal status. |
gate_session.completed | The session completed successfully. | Fulfill only after dedupe and any required trusted API reconciliation. |
gate_session.failed | The session failed. | Mark the order failed and show a retry path where appropriate. |
gate_session.expired | The session expired before completion. | Expire local checkout state and create a new session if the user retries. |
gate_session.cancelled | The session was cancelled. | Close the local checkout attempt without fulfillment. |
gate_session.kyc_package_accepted | A trusted KYC package was accepted for a session. | Store the audit correlation only; do not log PII-heavy payloads. |
Session events should be joined to your own order using the server-created session id, metadata, or user_reference you provided during session creation.
Gate events
| Event type | Area | Recommended action |
|---|---|---|
kyc.required | Gate | Move the user into the hosted KYC flow or show a pending KYC state. |
quote.consumed | Gate quote | Mark the quote as no longer executable. |
webhook.test | Delivery test | Confirm signature verification and endpoint reachability only. |
webhook.test is synthetic. It should never fulfill an order, credit a balance, or mark a real session complete.
Partner quota events
| Event type | Meaning | Recommended action |
|---|---|---|
partner.quota.warning | Usage is approaching a configured limit. | Alert operators and decide whether to slow or pause new session creation. |
partner.quota.exhausted | Usage limit has been reached. | Stop creating new dependent operations until the limit is resolved. |
Quota events are operational signals. They should not be exposed to end users as raw webhook errors.
Restricted rail events
The source contains pay-in and pay-out rail event names. These are not general public integration events. Use them only if your account is explicitly entitled for the rail flow and the contract/API review enables them.
| Event type | Area | Public handling boundary |
|---|---|---|
rail.pay_in.processing | Pay-in rail | Entitled rail partners only. |
rail.pay_in.settled | Pay-in rail | Entitled rail partners only. |
rail.pay_in.failed | Pay-in rail | Entitled rail partners only. |
rail.pay_in.cancelled | Pay-in rail | Entitled rail partners only. |
rail.pay_out.processing | Pay-out rail | Entitled rail partners only. |
rail.pay_out.settled | Pay-out rail | Entitled rail partners only. |
rail.pay_out.failed | Pay-out rail | Entitled rail partners only. |
rail.pay_out.cancelled | Pay-out rail | Entitled rail partners only. |
Do not publish provider names, bank details, treasury state, reserve logic, routing strategy, or private risk controls when handling rail events.
Product boundaries
| Product | Webhook status | Public-safe guidance |
|---|---|---|
| 0Gate | Source-backed signed events and delivery APIs. | Use as the default public webhook integration path. |
| 0Base | Foundation/review-only evidence. | Treat events as object/reporting model until live behavior is approved. |
| 0Pools | Partner-confidential/liquidity-sensitive evidence. | Use only approved partner-safe quote/trade events if enabled. |
| 0Link | App/link workflow docs only. | Do not assume a public event contract without approval. |
| 0Pools Scan | Explorer-style read visibility. | Use Scan pages for visibility, not as a webhook contract. |
Handler checklist
- Verify the signature with the raw body.
- Reject stale timestamps.
- Store the event id before fulfillment.
- Treat duplicate event ids as successful no-ops.
- Store object ids, event type, request id, timestamps, and your own references.
- Queue slow work after durable persistence.
- Reconcile terminal events with trusted API reads when the business action is high value.
- Never log API keys, webhook secrets, bank details, provider payloads, or PII-heavy KYC data.