Skip to main content
Webhooks can move events in either direction. Choose the direction based on where the event starts:
Serval does not provide a separate subscription system that pushes Serval events directly to arbitrary webhook URLs. Use a workflow for outbound webhook calls so you can control the trigger, payload, authentication, retries, and follow-up steps.

​
Outbound webhooks: send events from Serval

Use a workflow when a Serval event should notify an external system. The workflow determines when to send the notification and calls the destination through an existing integration or a custom application.
1

Connect the destination

Use a catalog integration when one is available. Otherwise, connect a custom application with the destination’s HTTPS API base URL and authentication. Custom applications support API keys, tokens, custom authentication headers, and OAuth 2.0 client credentials.
2

Create the workflow

Choose the workflow trigger that represents the event you care about, such as a Serval event, a schedule, or a help desk request.
3

Call the destination API

Add the integration’s API action. For a custom application, use the HTTP API request action and specify the request method, endpoint path, parameters, and JSON body. Serval applies the configured base URL and injects the stored authentication at runtime.
4

Test and publish

Test with a non-destructive endpoint or sandbox destination, confirm the receiving system accepts the payload, and then publish the workflow.
You do not need a new custom application for every outbound webhook. Workflows can reuse the same connected application when the calls share a base URL and authentication. Create another application instance when a destination uses different credentials, a different API base URL, or a separate environment such as production and sandbox.
Store API keys and client secrets in the integration setup, not in workflow code, inputs, or chat messages. Serval stores credentials encrypted and injects them server-side, so workflow authors do not need to handle the secret directly.

​
Inbound webhooks: receive events in Serval

Use a webhook-triggered workflow when an external system should start automation in Serval. Each published workflow receives a unique webhook URL and secret.
1

Create a webhook-triggered workflow

Select Webhook-triggered as the workflow type, build the workflow steps that use the incoming payload, and publish the workflow.
2

Copy the URL and secret

Open the trigger details and copy the unique webhook URL and webhook secret.
3

Configure the sending system

Configure the external system to send an HTTP POST request to the webhook URL. Send a JSON body containing the values the workflow needs.
4

Authenticate the request

Send the secret using X-Webhook-Secret: YOUR_SECRET (the default) or Authorization: Bearer YOUR_SECRET. The secret query parameter is supported for backward compatibility. Requests without a valid secret are rejected.
Treat the webhook URL and secret as credentials. Anyone with a valid secret can trigger the workflow. You can rotate the secret without changing the URL; the previous secret remains valid for seven days unless you revoke it immediately.

​
Which approach should I use?

  • A Serval event should notify another system: use an outbound workflow and call that system’s API.
  • Another system should start work in Serval: use a webhook-triggered workflow.
  • The destination already has a Serval integration: prefer its typed workflow actions over a raw HTTP request.
  • Several workflows call the same custom API: reuse one connected custom application when its base URL and credentials are the same.