One delivered lead, one enrollment: design vendor webhooks for retries
Plan lead delivery integrations with stable event IDs, secure authentication, durable receipt records and separate campaign enrollment checks.
·4 min read
Your CRM receives a lead and creates the contact, but the vendor does not receive the acknowledgment before its timeout. It sends the payload again. Without duplicate protection, the agency may get two records or enroll one person in the same campaign twice.
Treat retries as an ordinary integration condition. Agree on an event identity, persist receipt information and make the enrollment decision independently of contact creation. This guide describes a design to review with your developer and vendor, not a promise that every integration already implements it.
Agree on an event ID and delivery contract
Ask for a stable event ID that remains unchanged across retries, plus a vendor lead ID and event type. A new lead, correction and reassignment may be separate events concerning the same person. A phone number alone cannot distinguish them.
Document field names, required values, authentication, acknowledgment rules and retry behavior. Preserve the external identifiers in the intake record. If the vendor supplies no event ID, agree on a deterministic identifier before using automated campaign enrollment.
Authenticate and store before acknowledging
Validate the integration credential or documented signature and the payload before treating the delivery as accepted. Keep API keys in protected configuration; do not publish them in a blog, spreadsheet, support screenshot or URL shared with unrelated parties.
Persist an accepted event or durable queue entry, then acknowledge according to the vendor contract. If persistence fails, returning success can lose the lead. Long-running cleanup, routing and enrollment can happen after a durable receipt rather than inside the acknowledgment path.
Make duplicate protection survive multiple workers
Use a persistent uniqueness rule scoped to the workspace, vendor and event ID. An in-memory list disappears during restarts and does not coordinate multiple application instances. Keep processing state so a repeated event can resume safely or return its recorded result.
The same principle applies to communication-provider callbacks. Telnyx advises guarding against repeated webhook events and verifying signatures. Lead-vendor endpoints have their own contracts, so confirm their specific behavior instead of copying one provider's retry timing.
Check campaign eligibility separately
An existing contact is not automatically an eligible new enrollment. Check opt-outs, current conversation ownership, active enrollments, recent outreach and the configured purpose. A field correction should not resend the introduction unless that is an explicit approved action.
Record the enrollment decision and reason against the event. Distinguish 'contact updated, no new enrollment' from 'new eligible lead enrolled.' That gives support a useful explanation when the vendor reports a successful delivery but the agent sees no new text.
Rehearse uncertain outcomes
Test the exact same event twice, a timeout after receipt, malformed fields, an unavailable database and two simultaneous deliveries. Also test a legitimate update with the same lead ID and a different event ID. Verify contact totals and enrollment totals after each case.
Use safe test numbers and redact credentials from logs. Monitor failed or stuck processing with an owner and retry policy. A reliable integration tells you which stage completed, which is uncertain and how to recover without starting outreach again blindly.
Key takeaways
- →A retry needs the same stable event identity.
- →Acknowledge after durable acceptance, according to the vendor contract.
- →Persist duplicate protection across restarts and workers.
- →Contact updates and campaign enrollments require separate decisions.
Put this into practice with Text2Sale
Import leads, create follow-up campaigns, organize replies, and connect texting, calling, and appointments in one workspace.
Frequently asked questions
Is matching on phone number enough to prevent duplicate deliveries?
It can help identify a contact, but it does not identify the delivery event or prove that a new campaign enrollment is appropriate. Use stable source identifiers and enrollment checks as well.
Should every repeated webhook return an error?
Follow the vendor contract. A previously accepted event can often be acknowledged without repeating its actions. Return errors for actual failures that need retry, not simply because the event was seen before.