#Receive requests with a webhook adapter

An HTTP Inbound / Webhook adapter lets external systems start or continue processes — either Chester registers a webhook with them, or they post to a fixed URL secured by an API key or a signature.

#Two modes

flowchart TB
  subgraph W["Webhook — Chester registers"]
    D["Deploy / process waits"] --> R["Chester calls the provider's<br/>registration endpoint"]
    R --> P1["Provider posts to<br/>Chester's callback URL"]
  end
  subgraph S["Static URL — you hand it out"]
    K["You give the provider<br/>the URL and an API key"] --> P2["Provider posts to<br/>…/api/workflow/start/&lt;key&gt;"]
  end
  P1 --> C["Challenge, signature, filter,<br/>duplicate check"]
  P2 --> C
  C --> I["A process starts or continues"]

#Create a webhook adapter

1. Open the system, click Add adapter and choose HTTP Inbound / Webhook.
2. Give it an Adapter name and pick the Inbound mode: Webhook or Static URL.
3. For Webhook:
   • the Webhook base path, such as /v1.0 — the path only; the host comes from the environment;
   • under Authentication, how Chester logs in to register the webhook: a credential of type API key, Basic, Bearer or OAuth 2.0.
4. Click Create adapter. For a Static URL, Chester creates an API key at once and shows it with the URL — copy the key now, it is not shown again.

Challenge, signature and renewal are set afterwards, on the adapter's Configuration tab.

#Set up a webhook

On the Configuration tab of a webhook-mode adapter:

• Webhook details — where the provider's answer holds the webhook's id, and how to remove the webhook again.
• Challenge (Handshake) — how Chester answers the provider's verification request: Echo (send a value back), HMAC or Custom Token. With Store as signature secret, the secret the provider hands over in the handshake is kept and used to check signatures.
• Signature — the header, algorithm and encoding of the provider's signature, and optionally a shared Secret. A secret learned from a handshake replaces it; Forget learned secret drops it again, and the next handshake teaches a new one.
• Lifecycle & renewal — where the answer holds the expiry, and how to renew.

The registration request itself — path, body, extra steps — belongs to the action. See Systems and adapters.

⚠️ Webhooks are renewed on a fixed schedule: every three hours Chester renews those that expire within six hours, each for three more days. There is no setting for it.

⚠️ Inactivity & Heartbeat can be filled in, but has no effect.

⚠️ A process that waits for a webhook — a message catch event — needs a challenge of type HMAC or Custom Token; without one the registration fails.

#Set up a static URL

On the Configuration tab of a static-URL adapter:

• Endpoint & API key shows the URL with a Copy button, and Generate API key / Regenerate. A new key works at once; the old one stops working. The sender puts it in the X-API-Key header, or as Authorization: Bearer ….
• Verification & signature — for providers that sign their requests, such as Slack: an Echo answer to their verification request, and the signature check. With a signature configured, the API key is not needed.

A static URL is never open. If the adapter has neither an API key nor a signature check, Chester refuses every request to it with 401 — nothing starts, nothing continues, and a provider's verification request gets no answer. The process editor reports this as an error on every message start and catch event that uses the adapter. The same rule applies on the element's own webhook URL, …/api/webhook/inbound/<deployment>/<element>: without a signature check, it also wants the adapter's API key.

⚠️ The URL shown — …/api/workflow/start/<adapter id> — only continues waiting processes. To start a process, the provider must post to …/api/workflow/start/<correlation key> of the message start event — its Correlation Key, or the element's id if it has none. That URL is not shown anywhere.

⚠️ A static URL accepts JSON only, and ignores the action's transformations.

⚠️ An adapter switched to Static URL later has no key yet, and refuses every request until it has one. Save the mode, click Generate API key, and only then hand the URL to the external system.

#On the action

Per inbound action, on its detail page:

• Transformations — decode fields of the incoming body: Base64 → JSON, Base64 → Text, JSON Parse. Webhook mode only.
• Correlation Value Path — static URL only: the field of the body, such as event.thread_ts, whose value is matched against a waiting process's Correlation ID.
• Idempotenz — drop duplicate deliveries: a Key Expression over payload, headers and query, and how long to remember it (TTL, default 600 seconds).
• Cursor management and Delta query — for providers that only notify, then answer a query for the changes.

⚠️ Most labels of these settings are German, whatever the language of the screen.