Skip to content
Talki DevelopersBeta

appointment.created

POST

A new Talki appointment is committed. A booking made on a call arrives while the call is running, with call_id null. Sent to the account’s webhooks, and to an OAuth app that subscribes to it while its installation grants appointments:read.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
X-Talki-Signature
required
string

t=<unix seconds>,v1=<hex HMAC-SHA256>, the HMAC computed over <t>.<raw body> with the signing secret. During a secret rotation it carries one v1 per secret: accept the request if any matches.

X-Talki-Event
required
string

The event type, as in type.

X-Talki-Delivery
required
string

The event ID, as in id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
id
required
Id

The event’s ID, evt_ and 32 hex characters. Equal to the X-Talki-Delivery header and unchanged on a redelivery: deduplicate on it.

string
type
required
string
Allowed values: appointment.created
created_at
required
Created At

When the event was written, ISO 8601 with a +00:00 offset, possibly with microseconds. Parse it as an instant.

string format: date-time
api_version
required
Api Version

The dated contract version data is shaped for: the endpoint’s version on a webhook, the app’s on an app event.

string
account_id
required
Account Id

The Talki account the event happened on.

string
livemode
required
Livemode

false for an event from a sandbox account.

boolean
origin
required
Any of:
EventOrigin
object
source
required
Source

Where the change came from: voice (the assistant, during a call), dashboard (a person in the Talki web or mobile app), api (a credential through the API) or system (a rule Talki applied on its own). New values may be added; treat one you do not recognise as unknown.

string
credential_id
required
Any of:
string
idempotency_key
required
Any of:
string
installation_id
Any of:
string
data
required

The event’s payload.

object
object
required

The Appointment object, as the REST API returns it.

object
id
required
Id

Opaque Talki appointment identifier.

string
location_id
required
Location Id

The location the booking is at (GET /v1/locations), the one its service belongs to. Never null, and it never changes: moving a booking keeps its location.

string
status
required

active or cancelled. A cancelled appointment is retained rather than deleted, and can be restored — expect to see an id return to active via appointment.updated.

string
Allowed values: active cancelled
client
required
AppointmentClient

Who the booking is for. Always present; contact_id and phone_number are null when Talki has no number for the client. The name is the one the booking was taken under, exactly as the owner sees it, and may come from what the assistant heard on the call.

object
contact_id
required
Any of:
string
name
required
Name

First name the booking was taken under.

string
surname
required
Surname

Surname the booking was taken under.

string
phone_number
required
Any of:
string
service
required
Any of:
ServiceRef

The service an appointment is for, with enough to display it. Once the service is deleted, id is null and name is the one it was booked under. Fetch the full service with services:read.

object
id
required
Any of:
string
name
required
Any of:
string
start_at
required
Start At

Start of the booking, RFC 3339 UTC.

string format: date-time
end_at
required
End At

End of the booking, RFC 3339 UTC. For a multi-day stay this is the check-out moment, so the span covers the whole booking rather than one night.

string format: date-time
quantity
required
Quantity

Party size the booking carries — covers, people, items — for a service that asks for one (asks_quantity on GET /v1/services). Always 1 for a service that does not, so you can read it unconditionally. It is the booking’s total, not a breakdown per resource or unit.

integer
call_id
required
Any of:
string
notes
required
Any of:
string
created_at
required
Created At

When the booking was written, RFC 3339 UTC.

string format: date-time
updated_at
required
Updated At

Last change to the booking, RFC 3339 UTC. Show it to a human as “last modified”; do not sync on it: changes do not become visible in updated_at order, so a watermark on it can skip a booking permanently. Use the change feed’s next_cursor instead.

string format: date-time
Example
{
  "id": "evt_04d8e87897db4ecab459a456ea55e754",
  "type": "appointment.created",
  "created_at": "2026-09-22T15:04:06.218734+00:00",
  "api_version": "2026-10-01",
  "account_id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286",
  "livemode": true,
  "origin": {
    "source": "dashboard",
    "credential_id": null,
    "idempotency_key": null
  },
  "data": {
    "object": {
      "id": "a3fe45ee-572f-4677-b1dd-f36c21bb47de",
      "location_id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40",
      "status": "active",
      "client": {
        "contact_id": "8fbb25f2-4f3b-4496-8aea-f0fc66de512d",
        "name": "Giulia",
        "surname": "Bianchi",
        "phone_number": "+393331234567"
      },
      "service": {
        "id": "45c470b7-592a-42cd-8ce8-5d7a0a497d26",
        "name": "Haircut"
      },
      "start_at": "2026-10-08T09:00:00Z",
      "end_at": "2026-10-08T09:30:00Z",
      "quantity": 1,
      "call_id": "38d23d84-02d2-4418-b169-3608aa04a8f8",
      "notes": "First visit",
      "created_at": "2026-09-15T09:18:03Z",
      "updated_at": "2026-09-15T09:18:03Z"
    }
  }
}

Responses

Section titled “ Responses ”

2XX

Section titled “2XX”

Any 2xx acknowledges the event. Any other status, a redirect, or no answer within 10 seconds is a failure and is retried; 410 disables a webhook endpoint at once.