A callback arrives saying a call finished successfully. Your application closes a ticket, starts follow-up messages, and updates the customer record.
Before any of that happens, it needs to establish who sent the callback and what the event actually proves.
AI voice agent webhook security protects the boundary between telephony events and business actions. Validate the sender, resolve the correct tenant, control repeated events, and check workflow state before changing downstream records.
Treat the callback endpoint as a public interface
A hard-to-guess URL does not authenticate its caller. A JSON body with a valid-looking call ID is still untrusted input until the integration validates it using the provider's documented mechanism.
Twilio's webhook security guidance recommends validating its request signatures with the provided SDK libraries. It also notes that webhook parameters can evolve. Follow the current instructions for your provider and content type instead of copying a signature recipe from another service.
HTTPS and signature validation solve different problems: transport protection does not by itself prove a request came from your telephony provider.
Validate before changing the request representation
Capture the information needed by the provider's validator before middleware transforms it. Depending on the documented scheme, that can include the external URL, body bytes, or parsed form parameters.
Reverse proxies require special attention. An application may see an internal HTTP address while the provider signed a public HTTPS URL. Configure trusted proxy handling and the canonical external route deliberately. Do not weaken validation just because every request fails after deployment.
Test signature checks through the actual ingress path, with malformed and modified payloads as well as valid events.
Resolve the tenant from trusted configuration
After authenticating the event, associate its provider account and call reference with an existing server-side record. Do not let a tenant identifier supplied in a query string select which customer's credentials to use.
The same principle applies when one deployment serves multiple business numbers. Maintain the mapping from authorized provider accounts and numbers to the appropriate workflow and tenant.
Authentication of an event does not authorize every possible action. The call must also belong to the expected business process.
Make repeat delivery harmless
The following event-handling pattern is a proposed design; provider retry and ordering guarantees must be checked separately.
Persist a receipt identity, validate the transition against the current call state, and apply a business update once. Use a provider event ID when one exists. Otherwise, document a stable deduplication strategy suited to the actual event fields.
A call ID alone is usually too broad: one call can legitimately produce many events. A valid signature alone is also insufficient to prevent a repeated delivery from retriggering an action.
| Received event | Appropriate decision |
|---|---|
| New authenticated event for a known call | Apply a permitted transition |
| Previously processed event | Acknowledge without repeating the action |
| Event for an unknown tenant/call mapping | Quarantine or reject; investigate |
| Delayed event inconsistent with terminal state | Preserve evidence; do not blindly overwrite |
| Invalid signature | Reject before downstream processing |
Illustrative example: a completed call and an open booking
A hypothetical distributor uses a voice agent to arrange delivery appointments. A call-completed event arrives twice.
The first event closes the telephony session. It does not mark the appointment booked, because the scheduling API has not yet returned a confirmed booking ID. The repeat event makes no additional business change.
When the scheduling result arrives, the booking workflow records its own outcome. Staff can distinguish a finished phone call from a successful appointment.
For the broader data connection, see LuMay's voice-agent CRM integration guide.
Keep failure handling observable
Record a correlation ID, validation outcome, tenant-mapping result, event type, and processing state. Avoid dumping tokens, full transcripts, or unnecessary personal data into general application logs.
Alert on unusual validation failures and growing queues of unprocessed events. Follow the provider's response and retry contract when deciding whether to acknowledge before asynchronous processing. An early success response without durable receipt storage can lose events.
Frequently asked questions
Does a valid webhook signature make duplicate processing safe?
No. Signature validation authenticates the request under the provider's scheme; it does not mean the event has never been processed. Keep receipt identities and business-state checks so a repeated authenticated event cannot trigger the same downstream action again.
Should an older callback overwrite a newer call state?
Do not use arrival order alone as authority. Validate the proposed transition against the current state and the provider's event semantics. Preserve delayed events as evidence and reconcile conflicts instead of blindly reopening a completed workflow or reversing a confirmed outcome.
Can archived production callbacks be replayed directly against live write tools?
Use an isolated, authorized test path with sanitized data and controlled credentials. A replay can repeat downstream side effects if protections are incomplete. Test both signature handling and duplicate suppression without exposing customer records or creating real bookings.
What should you check when valid callbacks fail only behind the production proxy?
Compare the public URL and request representation expected by the provider's validator with what the application receives. Review trusted proxy configuration and body transformations. Fix the mismatch and retest through ingress rather than disabling signature verification to make callbacks pass.
Launch with evidence from the full path
Test invalid signatures, proxy URL differences, duplicate delivery, unknown call IDs, delayed callbacks, and worker restarts. Verify both the event record and the final business record.
When evaluating LuMay's voice-agent offering, ask how callback authentication and reconciliation work for your chosen telephony integration. A convincing conversation demo should be accompanied by evidence that its events cannot casually alter the wrong business record.
