Event webhooks

Event webhooks tell your own systems straight away when something happens in your account, for every assistant at once. You do not have to add an action to each assistant. Event webhooks are part of Enterprise; on other plans the card explains how to upgrade.

Event	When
conversation.ended	A conversation (call, SMS, WhatsApp or webchat) has ended and its summary and outcome are known.
lead.created	A conversation brought in a new request. Sent as soon as the request is saved, so often during the conversation, and once per request.
appointment.booked	An appointment is booked: in the built-in calendar (also when it is copied to Google Calendar or Microsoft 365) by the assistant or on the booking page, or by the assistant at Cal.com or eTermin.
appointment.rescheduled	An appointment is moved: by the assistant, or by the customer on the booking page.
appointment.cancelled	An appointment is cancelled: by the assistant, by the customer on the booking page or by your team under Appointments. Sent once: a cancelled appointment cannot be cancelled again or moved.

Test conversations from the dashboard never send an event.

What does not send an event

• Changes outside Yarla. If you move or delete an appointment directly in Google Calendar, Microsoft 365, Cal.com or eTermin, we don't hear about it and send nothing.
• A correction to a request later in the same conversation, and a new status your team picks. Fetch the request through the API when you need the latest state; conversation.ended carries the leadId.
• Completed or no-show on an appointment.

Add a webhook

Only an Admin can manage event webhooks.

1. Open Settings → Connections and scroll to Event webhooks.
2. Under Add a webhook, fill in the Address (https) of your endpoint.
3. Tick the Events you want. All of them are ticked by default.
4. Choose Add webhook.

You can have up to 5 webhooks. Under Address and events you change the address, the name or the events later; the switch turns a webhook off without deleting it. Changes save by themselves.

Adding or changing a webhook only works within 2 hours after you sign in, and only from your own login: not while a reseller or our support works in your account. See Changes that ask you to sign in again.

The address must be a full https:// address on the internet. Local and private addresses are refused.

What we send

Every event is a POST with Content-Type: application/json:

{
  "id": "evt_01JC4Z0Q8V9T3W6Y2B5N7K1M0P",
  "type": "conversation.ended",
  "createdAt": "2026-11-05T09:14:03.000Z",
  "businessId": "01JB...",
  "data": {
    "conversationId": "voice:...",
    "channel": "voice",
    "direction": "inbound",
    "customerPhone": "+31612345678",
    "customerPhoneVerified": true,
    "customerPhoneVerifiedBy": "caller_id",
    "customerName": "Jan Jansen",
    "outcome": "appointment_booked",
    "summary": "Jan wants his boiler serviced on Tuesday morning.",
    "durationSeconds": 184,
    "leadId": null,
    "appointmentId": "01JC...",
    "variables": {},
    "link": "https://.../inbox/voice:..."
  }
}

• lead.created carries the request: leadId, customerName, customerPhone, address, problem, urgency, preferredTime, summary and a link.
• appointment.booked, appointment.rescheduled and appointment.cancelled carry the appointment: appointmentId, serviceName, startAt, endAt, timezone, status, guestName, guestEmail, guestPhone, the custom fields and source. The link a customer uses to change the appointment is never included.
• customerPhoneVerified (on conversation.ended and lead.created) and guestPhoneVerified (on appointments) say whether the customer proved that number in the conversation: true or false. customerPhoneVerifiedBy and guestPhoneVerifiedBy say how: caller_id (the customer called from that number), sms_code, email_code, call_code, whatsapp or phone_change, and null when it was not proven. Both are null when there is no number, or when the appointment was not booked or changed in a conversation. See Verified or not verified.
• appointment.rescheduled also carries previousStartAt and previousEndAt: the time before the move. The appointmentId stays the same.
• At Cal.com and eTermin, that service keeps the appointment: appointmentId is null, provider is calcom or etermin, and externalId is their own id. When an eTermin appointment is moved or cancelled, we only send that id and the new time.
• The headers X-Yarla-Event (the type), X-Yarla-Event-Id (the same as id) and X-Yarla-Delivery (one per delivery) tell events and deliveries apart. A resend keeps the event id, so you can ignore an event you already processed.

Very long text is shortened so a delivery stays under 64 KB.

Check the signature

Each delivery carries an X-Yarla-Signature header, made with the Webhook secret on the same page, exactly as for HTTP actions. See Webhooks for how to check it.

Retries, test and resend

• Your endpoint has 5 seconds to answer with a 2xx. On a timeout, no connection, 408, 429 or a 5xx we try again, up to three tries in all, with a short pause in between. Another 4xx answer is final.
• There is no later retry. Under Last deliveries you see each delivery from the last 30 days with its result, and Resend sends the same body again.
• For Resend, we keep the body of each delivery for 30 days, or less when you keep conversations for a shorter time. It includes a phone number, name and summary. Deleting a conversation or contact does not remove it from the delivery: it stays until that period is over. To remove it at once, delete the webhook; that also deletes all its deliveries.
• Send test sends a sample event of the first type the webhook listens to, marked "test": true, and shows the result straight away.
• Send test and Resend together work up to 20 times an hour per account.

After a downgrade

Event webhooks are part of Enterprise. When you switch to a cheaper plan, or while an Enterprise payment is open, nothing is sent. Your webhooks stay saved, inactive, under Settings → Connections: they send again when you choose Enterprise again (and the invoice is paid), and you can still delete them. See Subscription & invoices.

Related articles

• Webhooks
• Connections
• HubSpot and Pipedrive
• API