Process 0Gate session lifecycle events
Map signed 0Gate session lifecycle events to your own order, deposit, checkout, or account state.
Session lifecycle events explain what happened to the hosted 0Gate session. Use them to move your own product state from pending, to processing, to a terminal fulfilled or closed state.
Your ledger still owns fulfillment
A 0Gate event tells you the hosted session state. Your system decides how that maps to credits, shipments, unlocks, invoices, balances, or support tickets.
Event map
| Event family | Typical meaning | Your action |
|---|---|---|
gate_session.created | Session was created server-side. | Attach the session id to your local attempt. |
gate_session.processing | A linked action started. | Show processing and wait for a terminal signal. |
gate_session.completed | The linked action succeeded. | Fulfill exactly once after verification and dedupe. |
gate_session.failed | A linked action failed. | Keep retry UX available or close the attempt based on your policy. |
gate_session.expired | The session passed its expiry without completion. | Close or recreate the attempt from your server. |
gate_session.cancelled | The session was cancelled. | Stop showing the hosted flow and expose retry or support. |
kyc.required | Hosted flow needs KYC before continuing. | Tell the user to continue inside 0Gate, not your own KYC path. |
State model
Worker pattern
async function processSessionEvent(event: GateWebhookEvent) {
const attempt = await attempts.findByGateSession(event.data.id);
if (!attempt) {
await supportQueue.enqueue({ reason: 'unknown_gate_session', eventId: event.id });
return;
}
await attempts.transitionFromEvent({
attemptId: attempt.id,
eventId: event.id,
eventType: event.type,
terminalOnly: true,
});
if (event.type === 'gate_session.completed') {
await fulfillOnce({ attemptId: attempt.id, sourceEventId: event.id });
}
}Guardrails
| Situation | Correct behavior |
|---|---|
| Duplicate completed event | Return success, do not fulfill again. |
| Failed event after processing | Keep internal state terminal or retryable according to your policy. |
| Browser says success but webhook is delayed | Show processing and wait or reconcile from server state. |
| Unknown event type | Store it, acknowledge it, and review handler support. |