Webhook Architecture
Outbound webhooks let an organization receive HMAC-signed event notifications at its own endpoints, with retry, backoff, and a dead-letter state. The platform also receives inbound webhooks from Stripe, Twilio, and WhatsApp.
#Purpose
#Architecture
Organizations register endpoint URLs (with a signing secret and a list of subscribed event types). A dispatch job reads the platform's event stream per organization from a cursor and enqueues a delivery for each (endpoint, event) whose type is subscribed; deliveries are idempotent per (endpoint, event).
Each delivery payload is signed with HMAC-SHA256; the signature is sent as a sha256=… value. Deliveries retry with exponential backoff and end in a terminal dead-letter state if they keep failing.
Inbound webhooks are handled for Stripe billing (verified with the Stripe webhook secret) and for Twilio/WhatsApp in the sales flows.
#How it works
Register endpoint
Fan-out
Sign & send
Verify at receiver
#Reference
#Subscribable event types
| Event | Meaning |
|---|---|
| lead_won / lead_lost | A lead was won or lost |
| proposal_accepted | A proposal was accepted |
| meeting.booked | A meeting was booked |
| invoice.paid | An invoice was paid |
| payment_failed | A payment failed |
| project.completed / task.completed | Delivery milestones |
| client.created | A client was created |
| billing.suspended | Billing was suspended |
| survey.submitted | A survey was submitted |
X-Signature: sha256=<hmac_sha256(secret, body)>#Implementation notes
- Deliveries are idempotent via a unique (endpoint, event) constraint.
- A per-org cursor tracks progress over the event stream.
- Managing endpoints requires the webhooks:manage scope or admin access.
#Limitations
Known limitations
- Outbound events are limited to the defined event-type list.
- Delivery is at-least-once with retries; receivers must be idempotent.
#Security considerations
Security
- Always verify the HMAC signature before trusting a payload.
- Keep the endpoint secret confidential.
- Return quickly and process asynchronously to avoid retries from timeouts.
#Best practices
- Verify signatures and treat delivery as at-least-once.
- Subscribe only to needed events.
- Monitor for dead-lettered deliveries.
#Related documentation
Still need help?
Can’t find what you’re looking for? The DevSphere OS team is happy to help.