# Webhooks

Zocdoc provides webhook support for developers to receive notifications from our platform. To date, webhook notifications cover changes to appointment statuses for appointments booked via `/v1/appointments/`, such as when an appointment is cancelled or rescheduled.

## Security

The appointment status webhook supports **HTTPS only** (except for testing within the sandbox environment). All webhook requests are signed with a shared key that is known only to Zocdoc and to the client. You should manually verify the signature of each request to ensure its origin from the Zocdoc API server and to confirm that it has not been tampered with during transit.

## Setting up Webhooks

1. Create an **HTTPS endpoint** on your server (HTTP can be used for testing purposes).
2. You can also use tools like [webhook.site](https://webhook.site) to test webhook responses within the sandbox.
3. In the sandbox environment, you may use any valid base64 string as a key to test.
Example key:
`g9Y9hjTUk9KKH7ffBRbtRmJYo2OISsdMK4flbfDa3zR=`
4. Submit your URL to the Zocdoc API team. The URL you provide will be hit by Zocdoc to post updates.


## Receiving and Processing Webhook Messages

Your endpoint should handle incoming webhook requests and parse the JSON payload.


```json
{
  "data": {
    "appointment_data": {
      "appointment_id": "62g4ar44-1yv9-0931-dl3t-e9c2174kks09",
      "appointment_updated_timestamp": "2023-06-14T17:06:54.9430804Z",
      "appointment_update_type": "updated",
      "changed_attributes": [
        {
          "attribute_path": "appointment.start_time"
        },
        {
          "attribute_path": "patient.uploaded_attachments",
          "attachment_type": "id_card"
        }
      ]
    },
    "data_type": "appointment_data"
  },
  "event_type": "appointment_updated",
  "webhook_timestamp": "2023-06-14T17:08:54.9430839Z"
}
```

**Note:**

* Currently the only supported value for `data_type` is `appointment_data` and for `event_type` is `appointment_updated`.
* Supported values for `appointment_update_type` are: `updated`, `cancelled`, and `created`.
* When the webhook is triggered due to attribute changes, the `appointment_data` payload **MUST** include a `changed_attributes` array.
Each object **MUST** contain at least an `attribute_path`.
For `patient.uploaded_attachments`, the object **MUST** also include the `attachment_type`.


## Verify the Signature of the Webhook

1. Convert the shared key provided by the Zocdoc API team to bytes as a **base64 encoded string**.
2. Extract the timestamp from the `webhook-timestamp` header.
The timestamp is in **Unix epoch time (seconds)** (e.g. `1686772989` = June 14, 2023 20:03:09 UTC).
3. Verify that the timestamp is within a few minutes (default: **5 minutes**) of the current time.
4. Convert the request body's **JSON payload to a string**.
*Note: Zocdoc may modify the schema at any time.*
5. Concatenate the signed payload:
`<webhook_timestamp>.<json payload>`
6. Encode this message as **UTF-8 bytes**.
7. Calculate the **HMAC SHA256** hash using:
  * The shared key as the key
  * The encoded message as the input
8. Compare the calculated hash with the signature in the `webhook-signature` header.


**Example `webhook-signature` format:**


```
v1:8KsUa1qDHGmJhK25hReYCRhOKkqxTYx7UC78f0FBkdA=;v2:8KsUa1qDHGmJhK25hReYCRhOKkqxTYx7UC78f0FBkdA=
```

Each signature is prefixed by the version (e.g., `v1:`) and separated by semicolons.

## Retries

Zocdoc will retry webhook events with **exponential backoff** for up to **48 hours** after the first attempt.

Zocdoc will retry if:

* A connection cannot be established with the developer's server
* No response is provided within **5 seconds**
* The connection is severed before a response


**Zocdoc will *not* retry based on the status code** returned by the webhook endpoint.