Managing Webhook Triggers
Learn how webhook triggers work in Foreman, how to view and filter them on the Webhooks page, and manage actions tied to Forma system events.
What are webhook triggers?
Webhook triggers are subscriptions Foreman creates with the Forma Webhooks API to listen for specific events and run actions in Foreman. Today they power two flows:
- Issue sync — created automatically the first time you push QA findings to Forma for a project. Listens for
issue.created,issue.updated, andissue.deletedevents and updates linked violations in Foreman accordingly. - Recurring QA checks — created when you set up a folder-level scheduled check. Listens for file version changes and triggers a QA run on the affected files.
Where to manage them
The Webhooks page (sidebar → Webhooks) lists every trigger across your tenant. Each row shows:
| Column | What it tells you |
|---|---|
| Name | The label assigned at creation (or (unnamed)). |
| System / Event | Which Forma system + event type the hook is registered for. |
| Action | What Foreman runs in response (e.g. QAIssueSync, QACheck). |
| Scope | The project (by name when resolvable) and folder the trigger is scoped to. Tenant-wide triggers show "tenant-wide". |
| Status | Active (green dot), Paused (grey), or Failed (red, with the error message inline). |
| Last triggered | When the hook last fired in your timezone. |
| Count | Total number of times the hook has fired. |
Filtering
The filter bar above the table accepts:
- A free-text search — matches name, system, event type, action type, project ID, or folder name.
- System — filter to one Forma system at a time.
- Action — only show triggers using a specific action handler.
- Status — Active / Paused / Failed.
- Project — only triggers scoped to a specific project (the dropdown lists every project that has at least one trigger, by name).
A Clear filters link appears whenever any filter is active.
Per-row actions
| Button | What it does |
|---|---|
| Events | Expands the row to show the last 100 webhook events received: timestamp, status badge (Processed / Received / Debounced / Skipped / Failed), event type, and action result. Shows debounce period, created-at, and the APS hook ID. |
| Pause / Resume | Toggles the trigger. Paused triggers stop dispatching to their action but stay registered with Forma. (Admin only.) |
| Delete | Unregisters the trigger from Forma and removes it locally. A confirmation dialog warns that future events will no longer reach Foreman. (Admin only.) |
Read access to the Webhooks page is open to anyone in the tenant. Pause / Resume / Delete buttons only render for organisation admins.
Troubleshooting
If a trigger shows Failed status, hover over the inline error message — APS often returns a clear reason (e.g. "Scope field not found", "Event Specification not found"). Common causes:
- The hub/region your APS app is configured for differs from the project's region.
- The user who originally created the trigger no longer has access to the project.
- The Forma webhook feature is unavailable on your subscription tier.
If issue status changes aren't flowing back to Foreman as expected:
- Check the trigger is Active here.
- Open Events for the trigger and confirm recent dispatches with Processed status.
- As a last resort, click Sync Forma on the run detail page to manually re-fetch every linked issue from Forma.
Next steps
- Pushing Findings to Forma Issues — how the Issue sync triggers get created in the first place
- Scheduling QA Checks — how recurring QA check triggers get created