Webhooks

Webhooks are used to connect inbound HTTP requests with flows. Webhooks conveniently facilitates three common use cases:

1. Consume incoming HTTP requests (webhooks) from external services and systems
2. Create API endpoints, powered by flows
3. Trigger flows with external HTTP requests

In Sirveo, a webhook is a simple configuration that associates a unique URL to a target flow, with optional authentication.

Note

Webhooks specifically supports system-to-system communication via HTTP. Use links to make web flows available to browsers.

Configuring webhooks

Before creating a webhook, you should have an existing graph or task flow to associate with it.

1. In the UI, navigate to Webhooks, under Flows in the menu

2. Click on the New Webhook button

3. Configure the webhook, and select save

   

The webhook identifier is a unique name, used to create the webhook’s URL. By default, it is a random value, which can be changed to something more descriptive.

Existing webhooks appear like this in the webhook list:

The UI shows the webhook’s associated URLs. The inbound URL is shown if the server’s inbound port and URL is configured.

In this case, the webhook is live, because the associated flow is active.

Good to know

When a webhook’s flow is not active, it’s URL will respond with a 404 status code.

Webhook URLs

For a webhook with an identifier of flow-one, with an active flow, the following URLs are available on Sirveo’s HTTP server(s):

`http://{SIRVEO_LISTEN_ADDRESS_ADMIN}/w/flow-one
`http://{SIRVEO_LISTEN_ADDRESS_INBOUND}/w/flow-one

Since the server is typically deployed in a container and/or behind a reverse proxy, the UI relies on the server’s URL configuration to determine the actual webhook URLs:

{SIRVEO_URL_ADMIN}/w/flow-one
{SIRVEO_URL_INBOUND}/w/flow-one

Good to know

If the server’s SIRVEO_URL_ADMIN and SIRVEO_URL_INBOUND settings are not configured correctly, the UI will provide incorrect URLs for webhooks (and links).

See network isolation for details on separating admin & inbound HTTP traffic.

Output mode

The Output Mode setting of webhooks determines the behaviour of HTTP response bodies.

By default, webhooks use output mode “None”, which is the safe default. In this case, HTTP responses only contains a status code, without a response body.

If a webhook’s output mode is changed to “Flow Output”, a webhook’s HTTP response body contains the output of it’s target flow, as JSON data. Flows may produce any output data that can serialize to JSON. This makes webhooks a powerful feature that can be used to create HTTP API’s.

Note

In Sirveo 0.3.0, webhook output modes were simplified. Prior releases had additional webhook output modes, which can now implemented more flexibly by using the Output Node in flows.

Understanding Flow Output

By default, the flow engine assumes that a flow’s output data is the output of the last node which executed in that flow.

As of Sirveo 0.3.0, the output node can be used to change the default flow output behaviour. When an output node runs at any stage of a flow, it’s output data becomes the flow’s output data. Multiple output nodes may be used in the same flow. Each output node will replace the flow’s output data.

Tip

As a general recommendation, webhooks which include flow output in their HTTP response bodies should use an output node. Having precise control over a flow’s output data is particularly important when:

1. The flow has conditional execution.
2. The flow performs operations which may fail

In both scenarios, unexpected inputs or errors may result in unintended output being included in webhook response bodies. Using output nodes can reduce or eliminate this possibility.

See the security reference for more detail.

Authentication token

When an authentication token is configured for a webhook, the server requires that incoming HTTP requests provide that token. If configured, tokens must contain at least 16 characters.

Given a webhook with an authentication token of 117881a82594c4ac5446b18a71500f5d, HTTP clients must provide the authentication token value as a request header:

Authorization: Bearer 117881a82594c4ac5446b18a71500f5d

Or as a query parameter in the URL:

.../w/identifier?auth_token=117881a82594c4ac5446b18a71500f5d

Note

If the request contains a header in the form Authorization: Bearer xxxx, the server ignores the auth_token query parameter, whether the provided header token is valid or not.

If an HTTP client does not provide a token, or provides a non-matching token, the server responds with a 401 status, and a JSON body:

{ "error": "Unauthorized" }

Note

Webhooks without a configured authentication token has no server-level authentication checks.

Tip

It is possible to implement custom webhook authentication schemes within flows, which can replace or further augment the built-in authentication token feature.

Flow input data

The server provides data from and about incoming HTTP requests to a webhook’s associated flow, as flow input data.

To learn about how the server turns HTTP requests into flow input, we can easily configure a flow to show us.

1. Make a new graph flow, named HTTP echo

2. Keep the default passthrough node

3. Activate the flow (top-right button in flow editor)

4. Create a new webhook.

   • As identifier use http-echo
   • Select the new graph flow
   • As output mode, use “Last”, since we want the output

5. Save the webhook

To clarify what we’re implementing here:

1. An HTTP client (your browser, shortly) opens the webhook URL
2. The server prepares input data for the flow, from the incoming HTTP request
3. The graph flow will output its input data, as-is, because of the passthrough node
4. The webhook’s “Last” output mode includes the flow output in the HTTP response body, in this case to the browser

Let’s see this in action; Click on the webhook’s URL, which will open in a new browser tab. You will see some JSON data that looks similar to this:

{
  "body": {},
  "client_ip": "127.0.0.1",
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "Accept-Encoding": "gzip, deflate, br",
    "Accept-Language": "en-US,en;q=0.5",
    "Connection": "keep-alive",
    "Cookie": "some_cookie=2c73cbc91db76cb4ac01e66ba; another_cookie=34432-x7",
    "Dnt": "1",
    "Host": "localhost:4000",
    "Referer": "http://localhost:4000/",
    "Sec-Fetch-Dest": "document",
    "Sec-Fetch-Mode": "navigate",
    "Sec-Fetch-Site": "same-origin",
    "Sec-Fetch-User": "?1",
    "Upgrade-Insecure-Requests": "1",
    "User-Agent": "Mozilla/5.0 (..."
  },
  "method": "GET",
  "query": {},
  "webhook_id": "068ce5ed-c87c-442f-81e4-cb0efd2ced05",
  "webhook_key": "http-echo"
}

Here we can see the metadata which the server adds to the flow input:

• client IP
• request method
• webhook ID and key (identifier)

And data from the HTTP request itself:

• all headers, as received by the server
• query parameters (none in this case)
• request body (empty in this case)

Let’s see what happens when I;

• add an authentication token to the webhook
• call the webhook URL from a non-browser client, like CURL or Postman
• add a query parameter, and some JSON data in the request body

{
  "body": {
    "some": "data in the request body"
  },
  "client_ip": "127.0.0.1",
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "gzip, deflate, br",
    "Authorization": "Bearer 0c628cb297db69f63c27b6362da3f0f6",
    "Cache-Control": "no-cache",
    "Connection": "keep-alive",
    "Content-Length": "43",
    "Content-Type": "application/json",
    "Host": "localhost:4100",
    "Postman-Token": "db35XXX...",
    "User-Agent": "PostmanRuntime/..."
  },
  "method": "POST",
  "query": {
    "a": "b",
    "c": "d"
  },
  "webhook_id": "068ce5ed-c87c-442f-81e4-cb0efd2ced05",
  "webhook_key": "http-echo"
}

HTTP response status

The server may reject certain HTTP requests to webhooks, or encounter errors before or during flow execution. Different scenarios result in different HTTP response status code:

status	when
404	Webhook identifier does not exist
404	Target flow not active
401	Authentication token required, but missing/invalid
500	Server is in restricted mode
400	Request body contains invalid JSON data
422*	Flow definition is not valid
422**	Flow engine rejected input data
400***	The flow executed, but encountered a runtime error
200	The flow executed without runtime errors

* Can happen, for example, when a flow definition is incorrectly modified directly in the database.

** Should not happen.

*** A response body error message will contain {"error":"Execution error"}, without additional detail. This is by design, since error messages may contain potentially sensitive information.

Note

If the server encounters any of the above error conditions while processing a webhook, custom status codes are ignored (see below).

Custom HTTP response status

If a webhook executes a flow, that flow can use the Status node to optionally configure the HTTP response code returned by webhooks to clients.

If configured by a Status node, valid status codes are in the 200-299, 400-499 and 500-599 ranges.

Note

A custom HTTP status is only used:

• if configured with a status node in the flow
• if that status node ran in the flow
• if, without a status node, the webhook would return the default 200 status, and not an error status (listed above)

Webhook constraints

• Webhooks supports task and graph flows (use links for web flows)
• Webhooks will not run flows in restricted mode
• Request bodies are ignored for HTTP request methods other than POST, PUT, and PATCH
• HTTP requests with request bodies must use the application/json content type header