Next (Convert Image) Previous (New User)

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]

Next (Convert Image) Previous (New User)