# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carescribe.io/webhooks/setting-up-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.