Webhooks

You can set up webhooks to make Studio push data to any arbitrary external service. Webhooks can be sent for the same triggers as our other notifications channels:

• API Error
• Job Complete
• Job Error

Configuration

Configuration is per-account. To set up webhooks, click Settings → Notifications → Webhook.

Enter the full URL where webhooks should be posted and enable the integration. Once set up, you can add, edit, or remove rules. The main URL will be used as the default, but you can override by specifying a different URL on a per-rule basis.

Expected Response and Retries

The webhook endpoint you provide should respond with a 200, 201, 202 or 204 response code. If we receive another response code, or the request times out after 3 seconds, we will cancel the request.

Payload Format

All payloads are delivered over HTTP/HTTPs as POSTs. Payloads can be sent in either JSON or XML format. JSON is the default; to use XML, configure that by editing each rule.

The basic payload format is:

{
  "type": "EVENT_TYPE",
  "payload": {}
}

EVENT_TYPE will be one of:

• api_error
• job_complete
• job_error

The payload will vary depending on the EVENT_TYPE.

Examples

API Error (JSON)

{
  "type": "api_error",
  "payload": {
    "id": 1,
    "code": 404,
    "message": "The resource could not be found",
    "path": "/api/v1/bad/path"
  }
}

Job Complete (JSON)

{
  "type": "job_complete",
  "payload": {
  	"download_url": "https://some.download/link",
    "id": 1,
    "photos": 10,
    "profile_id": 3,
    "skylab_id": 4,
    "state": "complete"
  }
}

Job Error (JSON)

{
  "type": "job_error",
  "payload": {
    "id": 1,
    "photos": 10,
    "profile_id": 3,
    "skylab_id": 4,
    "state": "error"
  }
}

Security

In order to authenticate webhook messages from Studio, we recommend the following:

You can issue yourself an authentication token for your webhook, and have it sent from Studio with every request. For example, configure it into your URI like https://hook.yoursite.com/poke?auth=abc123seekrettttt and have your hook server-side validate the token each time.