---

Webhooks

Webhooks can be used to receive notification of any changes in job status.

Job Types

• import
• export
• renderFrame
• renderAnimation
• renderThumbnailVRay
• renderThumbnailWebGL
• renderFrameWebGL
• liveRender
• command
• imageReducer
• vrayBrdfToStandard

Job Statuses

• pending
• working
• cancelled
• failed
• ok

Defining a Webhook

Currently, webhooks can only be defined by using Clara’s REST API. POST to https://clara.io/api/webhooks to create a webhook.

The following parameters are required:

• url (string): URL of your server. Clara.io will POST to this URL when a matched job status change occurs.
• jobTypes (array of strings): job types to listen for
• statuses (array of strings): job statuses to listen for

The following parameters are optional:

• scenes (array of strings, default [‘all’]): a list of scene ID’s to listen for
• active (boolean, default true): enable / disable the webhook.
• secret (string): if set, Clara.io will send a X-Clara-Signature header containing the HMAC hex digest of the body using this secret as the key

As with any clara.io REST API you may POST with content-type application/x-www-form-urlencoded, application/form-data or application/json.

When the webhook fires, data will be sent to your URL with content-type application/json.

Examples

content-type application/x-www-form-urlencoded

curl https://clara.io/api/webhooks \
  -X POST -u yourname:25ea87a1-1301-4bc4-9430-55112753e6a3 \
  -d "url=http://foo.example.com/hook" \
  -d "statuses[]=ok" \
  -d "statuses[]=failed" \
  -d "jobTypes[]=export" \
  -d "jobTypes[]=import" \
  -d "active=true"

content-type application/json

curl https://clara.io/api/webhooks \
  -X POST -u yourname:25ea87a1-1301-4bc4-9430-55112753e6a3 \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://foo.example.com/hook",
  "statuses": ["ok", "failed"],
  "jobTypes": ["export", "import"],
  "active": true
}'

Modifying a Webhook

PUT to https://clara.io/api/webhooks/${_id}

Listing Webhooks

GET https://clara.io/api/webhooks

Webhook Payload

When executing a webhook, Clara.io sends job data with content-type application/json. The job data may contain the following fields:

• _id
• owner
• sceneId
• status
• type
• createdAt
• files

Posts to your webhook’s URL will contain the following headers:

• Content-Type: application/json
• X-Clara-Delivery: a unique ID
• X-Clara-Signature: HMAC hex digest of the payload, using the hook’s secret as the key, if configured

Verifying the HMAC Digest

The X-Clara-Signature header is created with the following node.js expression:

'sha256='+crypto.createHmac('sha256', hook.secret).update(body).digest('hex')

It can be verified in Ruby with:

def verify_signature(payload_body)
  signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body)
  return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['HTTP_X_CLARA_SIGNATURE'])
end

Clara Node SDK

When using the Clara Node SDK:

$ clara webhooks:list [options]
$ clara webhooks:create [options]
$ clara webhooks:update [options]

---