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 POSTing 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 POSTed 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.