A typical lead journey now crosses several systems: a website form, an automation tool, a CRM, a messaging channel and sometimes a spreadsheet. Webhooks glue them together, and when a webhook silently fails, a real enquiry disappears. This runbook describes how to design those integrations so failures are rare, visible and recoverable.
1. Map the flow before building it
Write the journey as a table first:
| Step | Source system | Event | Destination | Payload owner |
|---|---|---|---|---|
| 1 | Website form | Form submitted (server confirmed) | Automation tool webhook | Web team |
| 2 | Automation tool | New lead | CRM - create or update contact | Marketing ops |
| 3 | CRM | Lead assigned | Sales notification channel | Sales ops |
| 4 | CRM | Lead qualified | Ad platform offline conversion upload | Marketing ops |
Every row needs an owner who is responsible when that step breaks.
2. Design the payload
- Include a unique event ID generated at the source (for example a UUID per form submission). Every downstream step should carry it.
- Include a timestamp in UTC and the source (form ID, page URL).
- Send only the fields the destination needs. Personal data you do not transmit cannot leak.
- Version the payload (
"schema_version": 2) so you can change it without breaking consumers.
3. Make every receiver idempotent
Webhook senders retry. Networks duplicate requests. If the same payload arrives twice, the receiver must not create two contacts or send two welcome messages.
- Store processed event IDs and ignore repeats.
- Prefer upsert (create or update by email or external ID) over blind create.
4. Handle failure deliberately
| Situation | Behaviour |
|---|---|
| Destination returns 5xx or times out | Retry with exponential backoff (for example after 1, 5, 15 and 60 minutes) |
| Destination returns 4xx (bad request) | Do not retry blindly - send to a dead-letter queue and alert |
| Destination rate-limits (429) | Respect Retry-After; slow down |
| All retries exhausted | Dead-letter queue + alert to the step owner |
A dead-letter queue can be as simple as a table or sheet that stores failed payloads with the error message, so they can be replayed after the fix.
5. Secure the endpoints
- Verify a signature (HMAC of the payload with a shared secret) on incoming webhooks when the sender supports it.
- Keep secrets in the automation tool's credential store or environment variables - never inside a shared document or a workflow description.
- Reject payloads older than a few minutes to limit replay attacks, if timestamps are signed.
- Use HTTPS only.
6. Monitor what matters
- Volume check: alert if form submissions arrive on the website but no leads are created in the CRM for a defined period during business hours.
- Error rate: alert on any dead-letter entry.
- Reconciliation: once a week, compare form submission counts against CRM lead counts for the same period. Differences reveal silent failures.
7. Change management
- Test changes in a sandbox or with a test form before touching the production flow.
- Keep a changelog of workflow edits: date, who, what, why.
- After any change, submit a real test lead end-to-end and confirm it arrives everywhere it should.
8. Incident checklist
- Identify the first failing step using the event ID.
- Pause downstream steps that could make things worse (for example automated messages).
- Fix the cause.
- Replay dead-letter payloads in order.
- Confirm with the reconciliation check and write a short incident note.
Further reading
- Automation should remove manual work without hiding failures. For an audit-first view of automation, see Gorilla Vibe's approach to AI marketing automation.
Top comments (0)