Using Webhooks

Instead of manually checking job status, you can opt to receive updates through webhook notifications. Whenever there is a change in the job status, a webhook call will be made to the specified URL.

A webhook call is triggered only when job status is changed to success or error.

Configuring webhooks

To configure the webhook, please follow these steps:

1. Sign in to your dashboard using your credentials.

2. Navigate to the "Settings" page.

3. Update the Webhook URL with the desired URL for receiving webhook notifications.

4. Save the changes. Once updated - webhook notifications will be automatically enabled for all jobs

Webhook Events

At the moment there is only one event supported:

• job_finished

Example webhook data

Webhook events are sent as JSON via POST requests to your endpoint.

The data that is available in each webhook is the same as job status response from GET /jobs/[job_id] endpoint. Each of our webhooks follows the same structure as below.

{
    "event": "job_finished",
    "data": {
        "job_id": 42,
        "status": "success",
        "result": {
            "datafile_url": "https://s3.amazonaws.com/..."    
        }
    }
}

Adding an endpoint to your app

You will need an endpoint in your app that serves as the receiver for all webhook requests. This should accept POST requests and be able to process and/or save each webhook as it is sent.

To tell SocialData API that a webhook request was received OK, return a HTTP 200 response. Any other response code will tell us that the webhook failed. At the moment we do not make repeated appempts to trigger failed webhook calls again.

We recommend that you store, at least temporarily, webhook events locally (either in your database or a cache) so that you can return the HTTP 200 response quickly and process the data outside of the webhook request. If your app ever fails to process a webhook, you will then have the data to make a bug fix and process it successfully without waiting for it to be resent.