TaadDocs
Help CenterAPIPolicies

Webhooks

List webhook endpoints

GET
/v1/webhook_endpoints

The endpoints that receive this workspace's events: the live ones for a live key, the sandbox's for a test key. At most 10 of each.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/webhook_endpoints"
{  "object": "list",  "data": [    {      "id": "string",      "object": "webhook_endpoint",      "url": "string",      "description": "string",      "events": [        "recording.created"      ],      "enabled": true,      "disabled_reason": "failing",      "failing_since": "string",      "livemode": true,      "created_at": "string",      "updated_at": "string"    }  ],  "has_more": true,  "next_cursor": "string"}

Add a webhook endpoint

POST
/v1/webhook_endpoints

Every event the endpoint takes is POSTed to url as JSON, transcripts and notes included, and signed the Standard Webhooks way (webhook-id, webhook-timestamp, webhook-signature). The answer holds the endpoint's secret (whsec_…), shown only this once: keep it to check signatures. The address must be https and public: private, loopback and link-local addresses are refused, when added and at every delivery. An endpoint made with a test key receives the sandbox's events (livemode: false).

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/webhook_endpoints" \  -H "Content-Type: application/json" \  -d '{    "url": "string"  }'
{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "recording.created"  ],  "enabled": true,  "disabled_reason": "failing",  "failing_since": "string",  "livemode": true,  "created_at": "string",  "updated_at": "string",  "secret": "string"}

Get a webhook endpoint

GET
/v1/webhook_endpoints/{id}

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/webhook_endpoints/string"
{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "recording.created"  ],  "enabled": true,  "disabled_reason": "failing",  "failing_since": "string",  "livemode": true,  "created_at": "string",  "updated_at": "string"}

Change a webhook endpoint

PATCH
/v1/webhook_endpoints/{id}

Change its address, its description or the events it takes, or turn it off (enabled: false). enabled: true works as POST …/enable: what it missed is sent.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 100

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/webhook_endpoints/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "recording.created"  ],  "enabled": true,  "disabled_reason": "failing",  "failing_since": "string",  "livemode": true,  "created_at": "string",  "updated_at": "string"}

Delete a webhook endpoint

DELETE
/v1/webhook_endpoints/{id}

Nothing more is sent to it, not even deliveries still waiting for a retry.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 100

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/webhook_endpoints/string"
{  "id": "string",  "object": "webhook_endpoint",  "deleted": true}

Send a test event

POST
/v1/webhook_endpoints/{id}/test

Sends an endpoint.test event to this endpoint now, signed as every delivery is, and answers with what the endpoint answered: its status and the first kilobyte of its body. Works on an endpoint that is off; a test never counts towards turning one off.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 100

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/webhook_endpoints/string/test"
{  "object": "webhook_test",  "event_id": "string",  "delivered": true,  "status": -9007199254740991,  "body": "string",  "error": "string"}

Rotate the signing secret

POST
/v1/webhook_endpoints/{id}/rotate_secret

Makes a new secret, shown only in this answer. For the next 24 hours every delivery is signed with both the new and the old one (two signatures in webhook-signature, space-separated), so you can switch without missing a delivery.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 100

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/webhook_endpoints/string/rotate_secret"
{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "recording.created"  ],  "enabled": true,  "disabled_reason": "failing",  "failing_since": "string",  "livemode": true,  "created_at": "string",  "updated_at": "string",  "secret": "string",  "previous_secret_expires_at": "string"}

Turn an endpoint back on

POST
/v1/webhook_endpoints/{id}/enable

Turns it on and sends what it missed: every event of the last 30 days that it takes and hasn't received, oldest first. An endpoint is turned off after four days of failed deliveries, and its owner is emailed; nothing is lost meanwhile. replayed says how many events were queued.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 100

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/webhook_endpoints/string/enable"
{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "recording.created"  ],  "enabled": true,  "disabled_reason": "failing",  "failing_since": "string",  "livemode": true,  "created_at": "string",  "updated_at": "string",  "replayed": -9007199254740991}

List events

GET
/v1/events

Every event of the last 30 days, oldest first, delivered or not: the way to catch up after downtime, or to work without webhooks. An event is listed a couple of seconds after it happens (so one is never skipped). A key sees the events its scopes can read (recording.* needs recordings:read, todo.* todos:read, calendar_event.* calendar:read); one with webhooks sees them all, as its endpoints receive them. Keep next_cursor and pass it as after next time to get only what's new. A cursor older than 30 days answers 410 cursor_expired: start again from GET /v1/recordings?updated_after=.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Query Parameters

after?string

next_cursor from an earlier call

Lengthlength <= 500
type?string

Value in

  • "recording.created"
  • "recording.ready"
  • "recording.failed"
  • "recording.updated"
  • "recording.removed"
  • "todo.created"
  • "todo.updated"
  • "todo.completed"
  • "todo.deleted"
  • "calendar_event.created"
  • "calendar_event.updated"
  • "calendar_event.deleted"
  • "usage.balance_low"
  • "usage.exhausted"
  • "endpoint.test"
limit?integer
Range1 <= value <= 100
Default20

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/events"
{  "object": "list",  "data": [    {      "id": "string",      "object": "event",      "type": "recording.created",      "created_at": "string",      "livemode": true,      "sequence": -9007199254740991,      "data": {        "property1": null,        "property2": null      }    }  ],  "has_more": true,  "next_cursor": "string"}

Get an event

GET
/v1/events/{id}

An event of the last 30 days, as it was sent, if the key's scopes can read it (as for the list).

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/events/string"
{  "id": "string",  "object": "event",  "type": "recording.created",  "created_at": "string",  "livemode": true,  "sequence": -9007199254740991,  "data": {    "property1": null,    "property2": null  }}

Wallet

Previous Page