Skip to content

Webhooks

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

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

When the job is finished DeepVA will make a POST call on your callback URL and pass the job inside the request body. The request to your endpoint will have a signature in the header. The signature is a string of the request body cryptographically hashed with a secret only your application and DeepVA knows about (HMAC-SHA512). You can define the secret under Settings on the DeepVA platform webpage. Using the signature, you can verify whether the request was issued by DeepVA and not someone else. To prevent replay attacks an additional parameter is provided (nonce) that represent the unix time and is therefore larger than before for each request. You should check both signature and nonce in your application.

The following events are ready to subscribe:

  • on_completed - job is done and has a final result
  • on_started - job has started. DeepVA is analyzing it
  • on_failed - job has failed

In the future, several module specific events will be added:

  • on_face_recognized - person XY has been recognized
  • on_unknown_face_recognized - unknown person has been recognized (e.g. trigger alarm)
  • on_object_recognized - object XY has been recognized
  • on_text_recognized - text XY has been recognized

This works well for live streams and could enable several use cases.

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

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

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