Webhooks

Webhooks are a way for systems to send automated messages or information to other systems. It is how, for example, Stripe notifies your accounting app when a client pays you, or how WooCommerce notifies you about new orders in Slack. Webhooks are a simple way of getting notified in real-time when something interesting happens.

opensentinel receives webhooks from the systems you care about and delivers those messages to you through your automation recipes.

Getting Started

An Automation Recipe - which is a combination of a Source, Handler, and Destination - defines a complete flow of a message processed by opensentinel. This guide walks through how to set up a webhook Source, which is only one of three components needed to define the complete flow of a message processed by opensentinel.

For a high-level walkthrough of how to combine Source, Handler, and Destination combine into an Automation Recipe read through our reference on Creating your first Automation Recipe.

Webhook URL

This section will walk you through setting up a webhook as an automation source as well as obtaining a unique URL endpoint for opensentinel to receive these webhooks.

  1. To begin, head over to the Automation Sources section of your dashboard.

    Automation sources

  2. Click the Add button to bring up the new automation trigger dialog. Choose Webhook from the dropdown list and click Create.

    Add a new automation source

  3. You'll then get a summary which will include your unique webhook URL.

    Add a new automation source result

How To Invoke

Typically you would configure your third-party systems to invoke these webhooks. However if you'd like to invoke them manually (e.g. for testing) here are a few basic curl examples to get you going.

opensentinel webhooks accept POST requests with the following Content-Type headers:

  • application/json
  • application/x-www-form-urlencoded
  • text/plain
  • multipart/form-data

How each of these messages is processed depends on your handler and integration destination.

JSON Example

curl -H 'Content-Type: application/json' \
     -d '{"test-message": "This is a test JSON message"}' \
     "https://automations.opensentinel.com/webhook?token=<TOKEN>"

Form Encoded Example

curl -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'test-message=This is a test form-encoded message' \
     "https://automations.opensentinel.com/webhook?token=<TOKEN>"

Plain Text Example

curl -H 'Content-Type: text/plain' \
     -d 'Hello, this is a plain text message' \
     "https://automations.opensentinel.com/webhook?token=<TOKEN>"

Multipart Form Example

curl -H 'Content-Type: multipart/form-data' \
     -F 'field={"test-message": "This is a multipart JSON message"};type=application/json' \
     -F 'field=This is a multipart plain text message;type=text/plain' \
     -F 'field=test-message=This is a multipart form-encoded message;type=application/x-www-form-urlencoded' \
     "https://automations.opensentinel.com/webhook?token=<TOKEN>"

Payloads, Headers, & Formats

As touched upon in the previous section, the webhook integration only accepts POST requests with a Content-Type header of application/json, application/x-www-form-urlencoded, text/plain, or multipart/form-data. When successful, the server will respond with an HTTP 202 and you should see your message processed shortly.

The endpoint also accepts gzip-compressed payloads when sent an appropriate Content-Encoding header. The following would produce the same output as the plain text example above.

echo "Hello, this is a plain text message" | gzip > body.gz
curl -H 'Content-Type: text/plain' \
     -H 'Content-Encoding: gzip' \
     --data-binary @body.gz \
     "https://automations.opensentinel.com/webhook?token=<TOKEN>"

There is an incoming-payload limit of approximately 200KB for each HTTP request.