Webhooks

What are Webhooks?

Webhooks are a way for you to receive events from Coredination in near-realtime. They are simply HTTP callbacks. You can subscribe to events of interest and we'll POST data to the URL you specify when those events occur.

Webhooks are available for a bunch of different types of events. They are organized into channels and event types. Channels are roughly equivalent to the resources (aka entities) in the API. Event types are also visible throughout other parts of the API and applications.

To add a subscription you need to specify:

• A valid URL that will receive our POST requests with a response status in the 200s.
• What channels you want to subscribe to.
• A regular expression event type filter (if any).

Subscribing to Webhooks

Webhook subscriptions are managed via the API. The curl examples below can of course be modified to use whatever language or mechanism you're using to talk to the API.

1. Create an API key

If you don't have an API key yet, head over to the API settings page and create one. All you need to fill out is an application name, the rest will be pre-filled. You can just call it My Webhook API Test or something like that for now.

2. Setup an endpoint to receive the webhook events

In order to receive the webhook events, you need to provide a publicly accessible endpoint that accepts JSON data.

You don't need to start by implementing your receiving endpoint and deploying on a server right away. We recommend you start using requestb.in. It allows you to inspect what the webhooks look like quickly in your browser. Once you start developing stuff on your local machine you can also use UltraHook to make it available on the interwebs.

3. Create a webhook subscription

At this point you need to decide what channel(s) to subscribe to. If you don't know or care at this point, try the job channel.

curl -i 'https://app.coredination.net/api/1/webhook' \
	-H 'API-Key: {my-api-key}' \
	-H 'Content-Type: application/json' \
	-X POST \
	-d '{ "url": "http://requestb.in/13jr22w1", "channels": [ "job" ] }'

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "uuid": "a540e834-5c54-4b07-b471-e3c1cb027af9",
    "active": true,
    "channels": [ "job" ],
    "eventTypeFilter": null,
    "url": "http://requestb.in/13jr22w1"
}

4. Trigger an event

Log in to the web application and create a job (or do anything else that generates a job event).

If you don't want to make any changes to your data but still want to test your webhook, you can issue an empty POST request to https://app.coredination.net/api/1/webhook/:subscriptionUuid/test and you'll receive a special webhook event with eventType="TEST".

5. Verify that the event was received

You should receive your event a few seconds after it was triggered. If you're using requestb.in just point your browser at your bin with ?inspect added to it, like http://requestb.in/13jr22w1?inspect.

Contents

Once you have a subscription going, your server will be bombarded with requests looking something like:

POST https://my.url.com/coredination/webhook
Content-type: application/json; charset=UTF-8
X-Webhook-Signature: 0cG7he1ZCphRTd7GYYW1CPPIWhk=

{
	"channel": "job",
	"eventType": "CREATE",
	"eventTimeStamp": 1377550047244,
	"entityClass": "Job",
	"entityUuid": "a6ba7c52-4da6-4cc3-bf52-db3e6684e0ab",
}

Security

The webhook request includes the X-Webhook-Signature header which contains an HMAC-SHA1 signature of the body of the request, signed with your API secret.

Verifying the signature is optional so you can get started without caring about that. Keep in mind though that without any kind of verification anyone could start sending requests to your endpoint as long as they know the URL.

You can use the following code example to generate the signature and compare with the one received in the header:

Timing and Reliability

Webhook requests will be fired off pretty much in real-time when an event has occurred. Requests are processed in a worker-queue scheme on our end, so they might be slightly delayed if our server load is high.

In case of network timeout, or if the endpoint responds with status code 404, 408, 409, 500, 502, 503 or 504, the request will be retried 5 times with 1 minute interval.

Channels and Events

The following table lists available channels and events.