Inbound Webhooks
Manage inbound sources and mappings from the Dashboard UI.
The Inbound section in the Dashboard UI provides two pages for managing webhook ingestion: Inbound Sources and Inbound Mappings.
Inbound Sources
The Sources page shows all configured webhook sources as a two-column card grid.
Each source card shows:
- Title and mnemonic code
- Active/Inactive status badge
- Origin — which origin interactions will be tagged with
- Verification algorithm — HMAC-SHA256, HMAC-SHA1, or Plain
- Description (if set)
- Webhook URLs — both the ID-based and mnemonic-based URLs with copy buttons
- View Mappings link — navigates to the mappings page filtered to this source
Creating a source
Click Create Source to open the creation modal.
Basic information
| Field | Required | Description |
|---|---|---|
| Title | Yes | Display name (e.g. "Stripe Webhooks") |
| Mnemonic | Yes | Unique short code (e.g. "STRIPE") |
| Description | No | What this source receives |
| Origin | Yes | Interactions from this source are tagged with this origin |
| Active | Yes | Whether the source accepts webhooks |
Signature verification
Configure how incoming requests are authenticated:
| Field | Description |
|---|---|
| Algorithm | HMAC-SHA256, HMAC-SHA1, or Plain (direct comparison) |
| Signature Header | HTTP header containing the signature (e.g. stripe-signature) |
| Encoding | Hex or Base64 |
| Signature Prefix | Prefix to strip before comparison (e.g. sha256= for GitHub) |
| Verify Secret | The signing secret — supports template variables like {{secret.stripeWebhookSecret}} |
The Replay Protection section (collapsed by default) adds:
| Field | Description |
|---|---|
| Timestamp Field | Header or payload field containing the event timestamp |
| Tolerance (seconds) | Maximum age before rejecting the event |
All fields that accept secrets support autocomplete for {{global.*}} and {{secret.*}} template variables.
Payload schema (optional)
Validate every incoming payload at the source level. Three input modes:
- Visual — add required field names one at a time
- JSON — paste a raw AJV JSON schema
- From Sample — paste a sample webhook payload and auto-generate a schema
Managing sources
Each source card has a dropdown menu with:
- Edit — reopen the creation modal with existing values
- Enable/Disable — toggle the source's active status
- Delete — remove the source and all its mappings
Inbound Mappings
The Mappings page shows all configured mappings as a responsive three-column card grid. Use the source filter dropdown to narrow by source.
Each mapping card shows:
- Title with priority badge (e.g.
P10) - Source name
- Active/Inactive status badge
- Description (if set)
- Flow badges — Resource Type → Action with custom colors and icons
- Details panel:
- Resource ID path
- Idempotency path (if set)
- Filter summary (e.g. "2 conditions")
- Field count (e.g. "5 mapped")
- Schema validation indicator (green checkmark if configured)
- Created date
- Action buttons: Test, Edit, and dropdown with Enable/Disable and Delete
Creating a mapping
Click New Mapping to open the full-page wizard. The wizard has five steps:
Step 1: Overview
Basic information about the mapping.
| Field | Required | Description |
|---|---|---|
| Title | Yes | Display name (e.g. "Stripe Checkout Completed") |
| Description | No | What this mapping does |
| Priority | No | Higher priority mappings match first (default: 0) |
| Active | Yes | Toggle to enable/disable |
Step 2: Configuration
Two-column layout:
Left column — Select the source. A preview card shows the selected source's details.
Right column — Select the resource type and action that will be used for created interactions.
Step 3: Schema
Optional AJV schema validation for this specific mapping. Three input modes (Visual, JSON, From Sample) — same as the source-level schema.
Additional field:
| Field | Description |
|---|---|
| Schema Root Path | JSONPath to a sub-object for validation (e.g. $.data.object). The schema validates this sub-object instead of the full payload. |
Defining a schema here also enables autocomplete for payload paths in the Matching and Field Mappings steps.
Step 4: Matching
Define filter conditions that determine which payloads match this mapping. All conditions use AND logic.
Each condition has:
| Field | Description |
|---|---|
| Field | JSONPath expression (e.g. $.type) — autocomplete from schema paths |
| Operator | equals, not_equals, contains, starts_with, ends_with, gt, gte, lt, lte, in, exists |
| Value | Expected value |
Add conditions with the Add Condition button. Remove with the ✕ button on each row.
An empty filter matches all payloads from the source.
Step 5: Field Mappings
Three sections:
Path Extraction — Required paths for the interaction:
| Field | Required | Description |
|---|---|---|
| Resource ID Path | Yes | JSONPath to extract the resource ID (e.g. $.data.object.id) |
| Idempotency Path | No | JSONPath for deduplication (e.g. $.id) |
Field Mappings — Map payload paths to interaction metadata fields. Each row has a target field name and a source JSONPath. If no field mappings are defined, the entire payload is used as the interaction object.
Metadata Paths — Map payload paths to interaction root-level fields:
| Key | Description |
|---|---|
| userId | User who triggered the event |
| sessionId | Session identifier |
| uowId | Unit of Work ID — auto-generates UUID if not mapped |
| interactionTimestamp | Original event timestamp |
| externalReference | External system reference ID |
All path fields support autocomplete from the schema defined in Step 3.
Testing a mapping
Click Test on any mapping card to open the test modal. Paste a sample webhook payload and click Run Test.
The test results show:
- Source schema validation — pass/fail with error details
- Mapping schema validation — pass/fail with error details
- Filter match — whether the payload matches the filter conditions
- Interaction preview — the interaction that would be created, including resource ID, extracted fields, and metadata