Webhooks
Structure for customer-facing webhook documentation and event handling guidance.
Webhook Model
Pinrail webhooks are the asynchronous companion to the operator API. Use them when you need your system to react to changes without polling.
Recommended Event Families
The current platform shape supports these customer-facing event families:
- terminal lifecycle updates
- provisioning job completion and rollback outcomes
- connector sync status changes
- settlement batch lifecycle updates
Exact schemas and event names should be treated as contract-owned by pinrail-platform until the generated reference is published here.
Delivery Expectations
Consumers should build for:
- at-least-once delivery
- idempotent event handling
- retry-safe endpoint implementations
- event logging keyed by Pinrail event id and delivery timestamp
Verification Guidance
Webhook consumers should:
- verify the request with the environment-specific signing secret
- reject unknown or expired signatures
- persist the delivery identifier before applying side effects
- return a success response only after durable acceptance
Operational Notes
If a downstream system is unavailable, prefer durable queueing and replay over synchronous business logic inside the webhook handler.
Examples
Webhook examples should be:
- minimal
- copy-pasteable
- language-neutral or duplicated per SDK where needed