Appen Webhook Basics

Webhooks provide callbacks between your web application and Appen. This integration point allows developers to create robust applications that interact with Appen and take actions based on the results that the platform provides.
 

Note: In this article, rows are referred to as "units".

Basics

Webhooks are enabled by setting the webhook_uri property for a Job.

When a webhook is enabled for a Job, Appen will post to that URL whenever an interesting event happens in your Job (see table below). Each POST will feature three parameters: signal, payload and signature.

• The signal describes the type of event that has occurred. Results for a row will be delivered with a unit_complete signal.
• The payload parameter will contain a JSON representation of the associated object. For example, when your job completes, you will receive the job_complete signal, and the associated payload will be a JSON representation of that Job.
• The signature contains a SHA1 encrypted version of your Webhook Token concatenated with the payload. (i.e., signature = sha1.encrypt( payload + webhook_token).
• unit_complete is the most frequently used webhook. The unit_complete payload includes all of the Judgments for the work completed, as well as additional useful aggregate statistics.

Note that the unit_complete event does not apply to test questions. To manually send webhooks for test questions, send a GET request to: https://api.figure-eight.com/v1/jobs/{job_id}/golds/fire_webhooks

Judgment Webhooks

You must set the send_judgments_webhook attribute on your Job to TRUE via a PUT request to  receive a webhook for every new judgment that your data collects:
curl -X PUT -d "job[send_judgments_webhook]=true" https://api.figure-eight.com/v1/jobs/{job_id}.json?key={api_key}

Error Handling

The Appen platform will retry posting the webhook several times with exponential backoff, if it encounters difficulties reaching your servers. A total of 30 attempts will be made to a failing webhook over the course of 165 minutes, with the first wait between attempts lasting 5 seconds and the last wait lasting 30 minutes. If the webhook is unsuccessful after the last attempt, we will automatically disable it - deleting your webhook_uri from the job's settings - and send an email informing you of the problem.

A post is considered a failure if your endpoint:

• responds with a non-200 status code,
• responds with a body including invalid JSON, and/or
• takes longer than 5 seconds to respond.

To keep the Webhook up and running correctly, please ensure that your server responds to each POST from Appen within 5 seconds, with an HTTP 200 (OK) header and an empty body (or valid JSON).

Events

Webhook Security

Using the webhook's signature: You will be able to sign Appen's posts by validating the sha1 signature attribute in the body of the payload or ‘X-Signature’ header.  The signature is a sha1 encrypted string of the unparsed payload concatenated with your secret webhook token ( i.e., signature = sha1.encrypt( payload + webhook_token ) ). You can validate the webhook by generating the same sha1 and comparing it to the signature sent with the payload ( e.g., webhook.valid? if payload[:signature] == sha1.encrypt( payload + webhook_token ) )

Via basic authentication: If your endpoint (webhook) supports basic authentication, you can set the webhook in your job using the following convention: 'http://username:password@webhook'. The webhook will be posted to your server using HTTP basic authentication via the username:password credentials that you provide.

Appen IP Whitelist: Appen does not maintain a whitelist of the IPs posting webhooks from our applications.