Webhooks

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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

{
  "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.