Webhooks
Webhooks provide callbacks between your web application and CrowdFlower. This integration point allows developers working with CrowdFlower to create robust applications that interact with CrowdFlower and take actions based on the judgments that the CrowdFlower platform provides.
Basics
Webhooks are enabled by setting the webhook_uri property for a Job.
When a webhook is enabled for a Job, CrowdFlower will POST to that URL whenever an interesting event happens to your Job. See the Events section below for details on exactly which events trigger webhooks.
Each POST that your app will receive will have two parameters: signal and payload.
The signal parameter describes the type of event that has occurred. See below for the types of events and signals that will be sent.
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.
unit_complete is the most frequently used webhook. The Unit payload includes all of the Judgments for the work completed, as well as additional useful aggregate statistics. See the Units documentation for details on its payload.
Note that the unit_complete event does not apply to gold units. To manually send webhooks for gold units, make a GET request to
http://api.crowdflower.com/v1/jobs/$JOB_ID/golds/fire_webhooksError Handling
If CrowdFlower encounters difficulties reaching your server for more than a few hours, it will automatically disable the webhook and send you an email informing you of the problems it has encountered with the URL you have provided. To keep the Webhook up and running correctly, please ensure that your server responds to each POST from CrowdFlower with an HTTP 200 (OK) header. The body of your response will be ignored.
You can re-enable the webhook by saving it again in the job’s Advanced Options. As soon as the webhook is re-enabled, all completed but unsent units will be posted to your server.
Events
| Signal | Description | Payload |
|---|---|---|
| unit_complete | One unit of work has all the judgments it needs. | Unit |
| new_judgments | Judgments were submitted. | Judgment |
| job_data_processed | The data uploaded for this Job has been processed. | Job |
| job_complete | All the judgments for the Job have been completed. | Job |
Guidelines
As our API matures, we will add support for more events. When you handle the POSTs from CrowdFlower, be sure your system responds gracefully with a 200 (OK) to new signal types. A future version of the API will allow subscribing and unsubscribing from different event types independently.
