Webhooks

Webhooks allow you to receive real-time notifications about events in DeepVA by subscribing to specific events.

This enables your application to respond to these events immediately, improving the overall integration and efficiency of your workflows.

There are two ways to subscribe to events in DeepVA:

Webhooks for Job Job lifecycle by providing a callback URL in the job creation request
Webhooks for API resources by subscribing to events via the new /webhooks endpoint

Webhooks for Jobs

To avoid spamming the /jobs endpoint you can subscribe to a webhook for several events. Add the webhook field to your Job object in the request body when creating a new job:

{
  "sources": ["{url-to-your-image}"],
  "modules": {
    "face_recognition": {
        "model": "celebrities"
    }
  },
  "webhook": {
    "events": ["job.face_recognition.on_completed"],
    "callback": "{your-endpoint-url-to-receive-callback}"
  }
}

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.

By combining these elements in a dot-separated format, the event names provide a clear and structured way to organize and refer to different events within DeepVA

The following events are available:

on_completed - job is done and has a final result
on_started - job has started. DeepVA is analyzing it
on_failed - job has failed
on_detailed_result - job has submitted a single result (DetailedResult)

There are more specific events on the mining module level:

job.landmark_recognition.on_segment_start - Landmark segment started (landmark appeared in the live stream)
job.landmark_recognition.on_segment_end - Landmark segment ended (landmark disappeared in the live stream)

The following example shows the request body that DeepVA sends to your exposed endpoint:

{
  "event": "job.face_recognition.on_completed",
  "timestamp": 1574251637.832497,
  "data": {
    "job": {JOB_OBJECT}
  }
}

You can read the job property to get the completed Job.

Webhooks for API Resources

Introduction

We introduced a new REST resource with the /webhooks endpoint to subscribe to events in DeepVA. Whenever you want to subscribe to a specific event, you can create a new Webhook object.

Read more about the Webhook resource here.

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

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

Here you can find a usage example.