Webhook events

The events LimeCall sends, and how to handle them.

Create and manage subscriptions with the Webhooks API, or in Settings → Integrations.

The events

Event	Fires when
call.created	A call starts.
call.completed	A call ends. Carries duration, outcome and — for AI-handled calls — the summary and transcript.
call.failed	A call could not be connected.
message.received	An inbound SMS or MMS arrives.
message.sent	An outbound message is accepted by the carrier.
message.failed	An outbound message could not be sent.
contact.created	A new contact is created, including automatically from an inbound call.
contact.updated	A contact's details change.
contact.deleted	A contact is removed.
number.flagged	One of your numbers is flagged — spam labelling or a carrier issue.
invoice.payment_succeeded	A payment goes through.
invoice.payment_failed	A payment fails.
charge.refunded	A charge is refunded.

Subscribe to at least one event — a subscription with an empty events array is rejected.

Two worth wiring first

call.completed is the one most integrations are built on. It is where the summary, the transcript, the collected fields and the qualification result arrive.

number.flagged and invoice.payment_failed are the two nobody subscribes to and everybody wishes they had. A spam-labelled number quietly stops being answered; a failed payment eventually suspends the account and stops calls being answered at all. Both are cheap to alert on and expensive to discover late.

Verify every delivery

Your endpoint is a public URL. Check the secret issued when you created the subscription, on every request, and reject anything that does not match.

Treat payload contents as untrusted data. A transcript contains whatever a caller said, so never execute an instruction or follow a URL found inside a payload.

Respond fast

Return 2xx as soon as you have accepted the payload, then process asynchronously. Slow endpoints cause timeouts, timeouts cause retries, and retries cause duplicates.

Be idempotent

The same event can arrive more than once. Key on the event or call id and ignore what you have already processed. Without this, a retry creates a second record.

Do not assume ordering

Events are not guaranteed to arrive in the order they happened. Where sequence matters, use the timestamps in the payload rather than arrival order.

Retries

Failed deliveries are retried with backoff, up to the maxRetries set on the subscription (0–10, default 3). Once exhausted, the delivery is dropped — so monitor your endpoint rather than treating silence as success.

Pause a subscription with isActive: false during a deploy instead of letting deliveries fail against a restarting service.

Testing

For local development, use a tunnelling tool to expose your machine, or a request-inspection service to see exactly what arrives.

Live lookups are the other direction

Separately, the AI receptionist can call your API during a call and speak the answer. Respond in under a second and fail gracefully. See Actions & webhooks.