Navigation
10.24. Connect External Systems with Inbound and Outbound Webhooks
Configure authenticated inbound webhooks and signed outbound events, map payload fields, and troubleshoot delivery logs, retries, and replay.
Webhooks let an MSP connect service activity to other systems without repeatedly checking for changes. An inbound webhook can turn an external alert into an action, while an outbound webhook tells another system about a ticket event. For Harbor Clinic, this can connect a monitoring feed to the service desk and pass ticket updates to an operational dashboard.
Before you begin
Open Settings > Security > Webhooks and choose Inbound or Outbound. Outbound administration requires the tenant's Admin role. Inbound operations use inbound_webhook permissions for reading, creating, updating, deleting, and replaying deliveries.
Have the external system's request format or receiving URL ready. The inbound Workflow handler requires Enterprise Edition; Direct action is a separate handler choice. A workflow must have a published version and be visible to appear in the selector.
Create an inbound webhook
- Select Inbound > New Webhook. Under Identity, enter Name, Slug, and an optional Description. The slug forms part of the receiving endpoint.
- Under Auth, choose Auth Method and complete its settings. Use a method your source system can supply.
- Under Idempotency, choose Key Source: HTTP header or JSONata expression. Supply the header name or expression and set Duplicate Window (seconds) so repeated delivery identifiers can be recognized.
- Under Handler, choose Handler Type. For Direct action, select Action, then provide values for its Target fields. For Workflow, select the published workflow to receive the webhook envelope.
- Review Webhook is active and select Create Webhook. Store any revealed Webhook secret in the source system before closing; it is shown only at that point.
- Copy the receiving URL displayed for the saved webhook into the source system and send a controlled request.
| Auth Method | Configuration to coordinate with the source |
|---|---|
| HMAC-SHA256 | Shared signing secret and Signature Header. |
| Bearer token | Bearer Token; an empty value on creation can generate one. |
| IP allowlist | Allowed IPs / CIDRs for the source. |
| Shared secret in path | Path Token and the offered Query Parameter setting. |
Use the generated URL and settings as displayed when configuring authentication. Keep credentials out of ordinary ticket notes or shared example payloads.
Map and test the inbound payload
Target fields offer Static value or Map from payload. Static values fit fixed routing choices; payload mappings use JSONata expressions to extract values from the incoming request. Required target fields must have mappings before saving.
After saving, select Capture sample request under Sample payload, then send a verified request from the source during the capture window. In Sample paths, focus a mapping field and select a path to insert it. Save edits with Save Changes.
Use Send test to open Send Test Request, supply Request Body JSON and Headers, and select Send Test. Treat tests as requests capable of invoking the configured action, and use suitable example data.
Create an outbound subscription
- Select Outbound > New Webhook and enter Name and the receiver's URL.
- Select the required Events from the available catalog, including ticket, project, and project-task events. Optionally use Ticket Filter to restrict ticket delivery to listed ticket UUIDs; blank means all matching ticket events.
- Add Custom Headers if the receiver needs additional authentication or context.
- Review Delivered fields. All fields are included by default; excluding fields still preserves the entity correlation key.
- Keep Verify SSL certificates enabled for a receiver with a valid certificate, review Webhook is active, and select Create Webhook.
- Store the one-time Signing secret in the receiver, then use Send Test from Deliveries to check the connection.
Retry Config JSON is available, but the form states that delivery cadence uses the platform's standard backoff schedule. Do not assume changing that JSON creates a custom retry timetable.
Investigate failures and retry deliberately
Inbound Delivery log shows recent verified requests with status, response, and duration. Use All Statuses to filter, then View to inspect request headers, request body, response body, and handler outcome. Replay redispatches through the current configuration and can repeat side effects, including ticket creation.
Outbound Deliveries shows events, attempt numbers, timestamps, response codes, duration, and errors or response content. After correcting the receiver, use Retry on a non-test delivery. Use Rotate Secret when replacing the signing credential, and update the receiver accordingly. Pause and Resume control the subscription without deleting it.
The expected result is an authenticated inbound action or a recorded outbound delivery for the selected event. Check field mappings for handler failures and receiver responses for outbound failures before repeating a request.