Signed webhooks, retries and cron processing
This section documents endpoint safety checks, event selection, HMAC verification, delivery retries and dead-letter behaviour.
Create a signed POS webhook
Create a signed POS webhookSet a name, safe public HTTPS endpoint and one or more events.
Open guide →GuideCopy the one-time webhook secret
Copy the one-time webhook secretStore the full secret immediately.
Open guide →GuideUnderstand webhook secret encryption at rest
Understand webhook secret encryption at restKnow secrets are encrypted with AES-256-GCM at rest.
Open guide →GuideUnderstand webhook encryption requirements
Understand webhook encryption requirementsKnow OpenSSL and a valid generated module key are required.
Open guide →GuideChoose webhook events
Choose webhook eventsSubscribe only to events the receiver processes.
Open guide →GuideSubscribe to product.created
Subscribe to product.createdReceive new-product events.
Open guide →GuideSubscribe to product.updated
Subscribe to product.updatedReceive changed-product events.
Open guide →GuideSubscribe to stock.changed
Subscribe to stock.changedReceive stock balance events.
Open guide →GuideSubscribe to order.created
Subscribe to order.createdReceive new order events.
Open guide →GuideSubscribe to order.updated
Subscribe to order.updatedReceive fulfilment/payment/order change events.
Open guide →GuideSubscribe to order.returned
Subscribe to order.returnedReceive full return events.
Open guide →GuideSubscribe to payment.updated
Subscribe to payment.updatedReceive payment reconciliation events.
Open guide →GuideSubscribe to purchase.received
Subscribe to purchase.receivedReceive purchase receipt events.
Open guide →GuideUnderstand webhook event IDs
Understand webhook event IDsUse the unique event identifier for receiver idempotency.
Open guide →GuideUnderstand webhook request headers
Understand webhook request headersRead X-Britixo-Event, X-Britixo-Event-Id, X-Britixo-Timestamp and X-Britixo-Signature.
Open guide →GuideVerify the webhook HMAC signature
Verify the webhook HMAC signatureCalculate SHA-256 HMAC over timestamp + dot + raw payload.
Open guide →GuideUnderstand webhook payload timestamps
Understand webhook payload timestampsUse the supplied timestamp in signature verification and replay policy.
Open guide →GuideUnderstand webhook endpoint SSRF protection
Understand webhook endpoint SSRF protectionKnow private/reserved/localhost/.local targets are rejected.
Open guide →GuideUnderstand webhook DNS validation and IP pinning
Understand webhook DNS validation and IP pinningKnow every resolved address is checked and delivery pins a validated public IP.
Open guide →GuideUnderstand webhook redirect blocking
Understand webhook redirect blockingKnow outbound delivery does not follow redirects.
Open guide →GuideUnderstand webhook connection timeouts
Understand webhook connection timeoutsDesign receivers for 5-second connect and 10-second total timeout.
Open guide →GuideUnderstand webhook retry scheduling
Understand webhook retry schedulingUse exponential delay with a six-hour cap.
Open guide →GuideUnderstand the eight-attempt limit
Understand the eight-attempt limitKnow a delivery becomes dead after its final failed attempt.
Open guide →GuideUnderstand webhook delivery uniqueness
Understand webhook delivery uniquenessKnow one webhook/event pair is queued once.
Open guide →GuideUnderstand cron webhook processing
Understand cron webhook processingKnow after_cron_run processes up to 25 queued deliveries per run.
Open guide →GuideUnderstand stale idempotency and rate-limit cleanup
Understand stale idempotency and rate-limit cleanupKnow the same cron hook removes expired protective records.
Open guide →GuideReturn a successful webhook response
Return a successful webhook responseRespond 2xx promptly after safe validation/queueing.
Open guide →GuideHandle duplicate webhook delivery safely
Handle duplicate webhook delivery safelyMake receiver logic idempotent by event ID.
Open guide →GuideHandle a webhook signature failure
Handle a webhook signature failureReject the request without processing and verify secret/raw-body handling.
Open guide →GuideTroubleshoot a webhook endpoint rejected as unsafe
Troubleshoot a webhook endpoint rejected as unsafeUse a publicly resolvable HTTPS endpoint with only public IPs.
Open guide →GuideTroubleshoot webhook delivery timeouts
Troubleshoot webhook delivery timeoutsReduce receiver latency and return before the module timeout.
Open guide →GuideTroubleshoot repeated webhook retries
Troubleshoot repeated webhook retriesInspect receiver response codes and signature handling.
Open guide →GuideTroubleshoot a dead webhook delivery
Troubleshoot a dead webhook deliveryCorrect the receiver; version 1.0.0 has no delivery replay UI, so use a controlled integration recovery plan.
Open guide →GuideDisable a webhook
Disable a webhookStop future event queueing from the settings list.
Open guide →GuideUnderstand webhook management limitations
Understand webhook management limitationsKnow the supplied UI creates and disables webhooks but does not edit, re-enable, delete or browse deliveries.
Open guide →GuideRun the webhook receiver checklist
Run the webhook receiver checklistVerify HTTPS, public DNS, signature, replay protection, idempotency, timeouts and 2xx response.
Open guide →