Listen for webhooks
Beta feature
Contact us at help@daily.co to get access.
Webhooks are a helpful way to receive notifications about events that are occuring in Daily. In order to use webhooks, you'll need to create a web server with an endpoint that Daily can POST
requests to as they occur. This allows you to track events in a more asynchronous and real-time fashion, instead of polling with API requests.
Available webhook endpoints
Configuring Webhooks
In order to configure a webhook, you'll need to create a HTTP server. You can use an online service like webhook.site for testing, or test locally using a a service like ngrok.
When an asynchronous event occurs, we'll send a POST
request to an endpoint you provide containing a request body that details the event. Once you have a server set up with an accompanying endpoint, you can send that to the POST /webhooks
endpoint to create a webhook. Webhook events are sent for all rooms on your domain.
And you'll receive a response like this:
When creating a webhook via the POST /webhooks
endpoint, Daily will send a request to the webhook server with a test request body.
If we do not receive a 200
status code relatively quickly, we will consider the endpoint faulty and return a 400
error.
It can be helpful to return a response immediately before handling the event to avoid webhook disruptions.
At this point, you can use the uuid
field and the GET /webhooks/:uuid
endpoint to receive information about your webhook.
Webhook Structure
state
Webhooks have a state
field that may either be "FAILED"
or "ACTIVE"
.
Your webhook may enter the FAILED
state if we fail to send an event to your webhook server 3 times. Succesful attempts will reset this counter. We require your webhook server to send a 200
status code relateively quickly, so be sure to respond to the request as soon as you receive it.
If your webhook has entered a failed state, we will no longer send events to that webhook. You can re-activate a webhook by sending a POST
request to /webhooks/:uuid
, where uuid
is your webhook uuid. This will once again send a test message to the endpoint provided, and if a 200
is returned, we will re-activate the webhook.
You may also update the other webhook fields such as eventTypes
if needed with this endpoint.
hmac
The hmac
field contains a secret that is shared between Daily and you.
Ensure that you do not share this secret publicly, otherwise you will not be
able to verify that an event came from Daily.
Webhooks provide an hmac
, which is a BASE-64 encoded HMAC-sha256 secret that allows you to verify that the event in question actually came from Daily. When POST
ing to your webhook server, Daily will provide two headers: X-Webhook-Signature
and X-Webhook-Timestamp
.
In order to verify the signature yourself, you'll need to compute the signature in a manner provided in the snippet below:
event
is the response body from the event that was POST
ed to your webhook server. From there, you can sign the content with the HMAC-sha256
string, and ensure that your signature matches the one in the X-Webhook-Signature
header. As only Daily and you hold the hmac
, this comparison ensures that the request came from Daily.
failedCount
This is incremented every time Daily fails to send an event to the given webhook endpoint. This can happen if your server is not responding quickly enough or if it is returning a non-200
status code. When this happens 3 times, the webhook will enter the FAILED
state. If we have a succesful response at any time before this we will reset your failedCount
to 0. Thus, intermittent failures should not cause the circuit breaker to flip.
basicAuth
You may provide a basicAuth
field when creating a webhook if you'd like Daily to send an Authorization
header with a Basic {secret}
value. This can be checked by your endpoint and used as an additional shared secret to ensure that you are only processing verified events from Daily.
Webhook Events
We provide several webhook events that you can subscribe to. See the webhook events index for more details.