Webhook Resource

Definition

This is an object representing a webhook subscription to receive events from DeepVA. Each webhook contains a single event to subscribe to and a callback URL.

When an event occurs, DeepVA sends a POST request to the callback URL with the event data.

You can retrieve it to see the information of the webhook.

ENDPOINTS

GET /v1/webhooks/

POST /v1/webhooks/

GET /v1/webhooks/{WEBHOOK_ID}/

PUT /v1/webhooks/{WEBHOOK_ID}/

PATCH /v1/webhooks/{WEBHOOK_ID}/

DELETE /v1/webhooks/{WEBHOOK_ID}/

Attributes

Top level attributes

Name	Type	Description
id	string	Global identifier to access the actual resource
event	string	The name of the event to subscribe to
url	string	The callback URL from the third-party system
hmac_secret	string	A secret string to sign the payload for verification
description	string	An optional textual description
time_created	string	Creation time of the webhook (ISO Time String)
exp_backoff	boolean	Currently not used at all. Reserved for the future.
retry_limit	integer	Currently not used at all. Reserved for the future.

Available events

The event names follow a hierarchical path structure, with each component separated by a dot.

{namespace}.{event_name}

The path consists of multiple parts: the namespace as path and the specific event name.

These events are available currently:

Event	Description
deepva.transcript.on_created	The event is triggered whenever a new Transcript is created.
deepva.transcript.variant.version.on_created	The event is triggered whenever a new Version of a Transcript Variant is created. It covers the editing of the transcript after hitting the save button in the UI or the creation of the initial version when a new transcript is created.
deepva.transcript.variant.version.paragraph.on_updated	The event is triggered whenever a paragraph text is changed
deepva.export.on_started	The event is triggered whenever a export has been started
deepva.export.on_completed	The event is triggered whenever a export has been completed and is available to the user
deepva.export.artifact.on_created	The event is triggered whenever a export artifact (the actual exported file) is created

Usage example

Here is an example of how to create a new webhook event subscription:

In the following example we are subscribing to the event deepva.transcript.on_created which is triggered whenever a new transcript is created.

BashPython

curl -d '{"event": "deepva.transcript.on_created", "url": "{your-endpoint-url-to-receive-callback}", "hmac_secret": "{a-secret-string}" }' -H "Content-Type: application/json" -H "Authorization: Key {your-api-key}" -X POST https://api.deepva.com/api/v1/webhooks/

# coming soon

When the event occurs, DeepVA sends the following POST body to the callback URL:

{
  "event": "deepva.transcript.on_created",
  "id": "42a1baeb-0919-4589-9d08-2186f567fa38",
  "data": {
    "transcript": {
      "id": "5f9b6eee-c1b6-4bf3-b4f7-d3a6bf450776",
      "tag": "",
      "job": {
        "duration": 214.015,
        "errors": [],
        "id": "f6a9cf1b-5ff5-4317-be21-73d999d447df",
        "is_synced_to_kg": false,
        "media_type": "video",
        "modules": {
          "speech_recognition": {
            "detect_silence": true,
            "dictionaries": [],
            "dump_docx": false,
            "dump_srt": false,
            "enable_ner": false,
            "enable_vad": false,
            "format_paragraph": false,
            "language": "auto",
            "merge_voice_gap_seconds": 0.5,
            "mode": "quality",
            "progress": 1,
            "state": "completed",
            "translation_language": "none",
            "underline_words_in_srt": false,
            "vad_threshold": 0.9,
            "word_level_timestamps": false
          }
        },
        "progress": 1,
        "result": {
          "detailed_link": "https://api.deepva.com/v1/jobs/f6a9cf1b-5ff5-4317-be21-73d999d447df/detailed-results/",
          "summary": [
            {
              "info": {
                "duration": 5.76,
                "fps": 25,
                "resolution": [
                  960,
                  540
                ],
                "total_frames": 144
              },
              "items": [],
              "media_type": "video",
              "source": "storage://78jTuGOKO15AxHDCQccK"
            }
          ]
        },
        "sources": [
          "storage://78jTuGOKO15AxHDCQccK"
        ],
        "state": "completed",
        "tag": "",
        "time_completed": "2024-06-13 15:08:26.114000",
        "time_created": "2024-06-13 15:04:47.442000",
        "time_started": "2024-06-13 15:04:52.099000"
      },
      "source": "storage://78jTuGOKO15AxHDCQccK",
      "time_created": "2024-06-17 10:09:34.376666",
      "time_updated": "2024-06-17 10:09:34.380000"
    }
  },
  "timestamp": 1718618974.4123013,
  "hmac_signature": "2g9mteNXBFk0tz7eMqUQuu1JOJWfKmSEqSdOPmDsZ3s="
}

The payload contains the event name, a unique event ID, the event data, a timestamp, and a HMAC signature for verification.

The data field contains the actual resource object that triggered the event. In this case, it is a Transcript object.

The HMAC signature can be used to verify the authenticity of the content of the data field. The HMAC signature is calculated using the HMAC-SHA256 algorithm with the hmac_secret provided in the webhook object.

The verification process is optional but recommended to ensure the integrity of the data.

A service such as https://webhook.site can be used to test the webhook subscription and receive the POST requests from DeepVA without the need of a server.