> For the complete documentation index, see [llms.txt](https://docs.carescribe.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carescribe.io/webhooks/setting-up-webhooks.md).

# Setting up Webhooks

## Overview

Caption.Ed allows you to subscribe to webhook events that notify your application in real-time when an event occurs. Webhooks are offered for all events that can occur as an act of another user (for data which you have access to) or when you call an API service that performs a background operation such as transcribing a media object.

{% hint style="info" %}
Caption.Ed implements strict API rate limiting to ensure good quality of service. Our API endpoints should not be polled unless otherwise stated. Instead utilise webhooks to ensure that interactions are delivered in real-time and in an efficient manor.
{% endhint %}

## Events

The following events can be subscribed to:

| Event Name                  | Description                                       | Resources Included |
| --------------------------- | ------------------------------------------------- | ------------------ |
| `transcription.transcribed` | A transcription has been sucessfully transcribed. | `Transcription`    |
| `transcription.created`     | A transcription object has been created           | `Transcription`    |

## Subscribing to events

To subscribe to webhooks you can use the Developers dashboard to register a new Webhook Endpoint or use the API to create a Webhook Endpoint.

Here is an example of subscribing to a couple of events using the API:

```bash
curl https://api.carescribe.io/webhook_endpoints \
  -H 'Accept: application/vnd.captioned.v1' \
  -H 'Authorization: Bearer {access_token}' \
  -d callback_uri="https://example.com/my/webhook/endpoint" \
  -d enabled_events[]="transcription.created" \
  -d enabled_events[]="transcription.transcribed"
```

For more details and examples you can visit the API reference:

{% content-ref url="/pages/-MZIA16QXYdWhv0cuR1m" %}
[API Reference](/api-reference.md)
{% endcontent-ref %}

## Receiving events

All events are sent you you in real-time to your provided callback URI as `POST` requests. Here is an example event based on the `transcription.transcribed` event:

```javascript
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "webhook_event",
    "attributes": {
      "created_at": "2030-01-01T14:00:00.000Z",
      "event_type": "transcription.transcribed"
      "uri": "https://example.com/webhooks/captioned"
    },
    "relationships": {
      "subject": {
        "data": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "transcription"
        }
      }
    }
  },
  "included": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "transcription",
      "attributes": {
        "title": "Steve Jobs' 2005 Stanford Commencement Address",
        "duration" 12345,
        "average_confidence": 0.912345678901234,
        "media": {
          "url": "<SIGNED_GCS_MEDIA_URL>",
        },
        "transcriptions": [
           {
             "format": "google_stt",
             "url": "<SIGNED_GCS_MEDIA_URL>",
           },
           {
             "format": "vtt",
             "url": "<SIGNED_GCS_MEDIA_URL>",
           }
        ],
      }
    }
  ]
}

```

{% hint style="warning" %}
**Important**

Your server should respond to webhook events with a `2xx` status code.

If we receive a status code that is not successful then we'll re-attempt delivery of the webhook event up to 5 times.
{% endhint %}