# Delivery and retries

## What your endpoint must do

- Accept an HTTPS `POST` with a JSON body.
- Return a `2xx` status within 30 seconds. Any other status, or no response in that time, counts as a failure.
- Handle the same event more than once.

Respond first and do slow work afterwards. A queue or background job works well.

## Retries

A failed delivery is retried up to 4 more times, about 15 minutes apart.

| Attempt | When |
| --- | --- |
| 1 | Right away |
| 2 | About 15 minutes later |
| 3 | About 30 minutes later |
| 4 | About 45 minutes later |
| 5 | About 60 minutes later |

After 5 failed attempts the event is marked failed and is not retried again. You can retry it by hand from **View Event Logs** in the dashboard.

On each retry:

- `X-YAA-Webhook-Id` stays the same.
- `X-YAA-Webhook-Signature-Timestamp` and `X-YAA-Webhook-Signature` are new.
- The body can differ. An automatic retry reads the record again before it sends. A retry by hand sends the body from the first attempt.

A failing endpoint is not turned off. It keeps receiving new events.

## Duplicates

You can receive the same event more than once, for example when your endpoint processed a request but the response did not reach us in time.

Save each `X-YAA-Webhook-Id` you handle and skip any you have seen before.

## Order

Events can arrive out of order. A retried event can arrive after a newer one.

- Use the IDs in the payload (`test_id`, `note_id`, `session_id`) to find the record to update.
- Notes have `updated_at`. Keep the note with the newest one.
- Other events have no date that marks a version. Keep the most recent one you receive.
- Delete and cancel events have no date. After one arrives, ignore later events for that `test_id`, `note_id`, `meeting_id` or `session_id`.
- A series cancel covers only sessions from `effective_from` onward. Keep handling other events with that `recurrence_group_id`.

## Several endpoints

You can add more than one webhook. Each one gets its own delivery and its own retries. A failure on one endpoint does not resend the event to an endpoint that already received it.

## Event logs

**View Event Logs** shows every event sent to a webhook, its status, the number of attempts and your endpoint's last response.

| Status | Meaning |
| --- | --- |
| Pending | Waiting for the first attempt. |
| Retrying | An attempt failed. Another is scheduled. |
| Delivered | Your endpoint returned a `2xx` status. |
| Failed | All 5 attempts failed. |

We keep the first 1,000 characters of your response body in the log. Don't return sensitive data in webhook responses.
