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.

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.

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:

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:

API Reference

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:

{
  "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>",
           }
        ],
      }
    }
  ]
}

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.