Skip to main content

Triggering Workflows with Webhooks

This guide sets up a GitHub webhook that starts a code-review workflow whenever a pull request is opened against main. The same steps work for other providers — differences are listed at the end.

Before you start​

  • A workflow to run. Because webhook runs get no attribute values, its first node should work from the event itself — for example an Agent node whose input message is:

    Review the pull request described in this GitHub event and post your findings.

    ${initial_message}

    ${initial_message} holds the event type, a short summary and the raw payload. See Webhooks.

  • Admin access to the GitHub repository.

1. Create the webhook in FYAI​

  1. Go to Settings → Webhooks and click New Webhook.
  2. Fill in:
    • Name — "GitHub PR review"
    • Provider — GitHub
    • Linked Workflow — your review workflow
    • Leave it Active.
  3. Click Save.

The ENDPOINT box now shows the webhook URL and the start of its secret. You'll copy both in step 3.

note

Choosing this webhook in the workflow's Trigger node (Trigger Type: Webhook) only displays the URL in the builder. What starts runs is the webhook's Linked Workflow.

2. Add filters​

Without filters, every event GitHub sends starts a run. Narrow it down:

  1. Under EVENT FILTERS, click the PR Opened chip. This adds event_type Equals github.pull_request.opened.
  2. Click Add Filter and set:
    • Field — payload.pull_request.base.ref
    • Operator — Equals
    • Value — main
  3. Click Save.

A delivery must pass every filter.

Optional: GitHub can send several events for the same commit. Turn on DUPLICATE SUPPRESSION and click One run per commit so a second run doesn't start while the first is still going.

3. Configure GitHub​

  1. In the repository, go to Settings → Webhooks → Add webhook.
  2. Payload URL — paste the FYAI webhook URL (Copy URL).
  3. Content type — application/json.
  4. Secret — paste the FYAI secret (Copy Secret). GitHub-provider webhooks reject unsigned deliveries, so this is required.
  5. Which events? — choose Let me select individual events and tick Pull requests.
  6. Keep Active ticked and click Add webhook.

GitHub sends a ping event straight away. It appears in the FYAI log as No match (it isn't a pull request event), which confirms the URL and secret work.

4. Test it​

Open a pull request against main. Then:

  1. In FYAI, select the webhook and click Logs. The delivery should show Matched with response code 200.
  2. Go to Build → Missions → View all history. The new run is listed; open it to watch on the mission canvas. In the workflow's Executions, its Trigger shows Webhook.

Troubleshooting​

What you seeLikely cause
GitHub shows 401The secret in GitHub doesn't match. Copy it again, or Regen Secret and update GitHub.
GitHub shows 410The webhook is Disabled in FYAI.
GitHub shows 409GitHub redelivered an event that already started a run in the last 5 minutes.
GitHub shows 423The linked workflow has been deactivated.
Log shows No matchA filter failed. Check the event type and field paths — the API's delivery log (GET /webhooks/{id}/logs) includes the full payload and which rule failed.
Matched but no missionThe webhook has no Linked Workflow.
Mission runs but agents ignore the eventThe node's input message doesn't include ${initial_message}, or it relies on attributes, which are empty for webhook runs.

Use GitHub's Redeliver button on a past delivery to test without opening another pull request (it is refused as a replay if that delivery already started a run in the last 5 minutes).

Other providers​

ProviderSetupUseful filters
GitLabProject Settings → Webhooks. Paste the URL, and put the FYAI secret in Secret token — required for GitLab-provider webhooks.event_type Starts With gitlab.push or gitlab.merge_request (event types are like gitlab.push_hook).
JiraJira's system WebHooks settings. Paste the URL.event_type Starts With jira.jira:issue_created or jira.jira:issue_updated. Preset: One run per change.
BitbucketRepository Webhooks. Paste the URL.event_type Starts With bitbucket.repo:push.
CustomAny system that can POST JSON. Put an event_type field in the body or send an X-Event-Type header if you want to filter on event type.Any payload.… or header.… field.

For Jira, Bitbucket and Custom webhooks the URL token alone authenticates deliveries, so keep the URL private.

warning

Slack is listed as a provider, but FYAI does not answer the URL-verification challenge that Slack's Events API sends when you register a URL, and Slack payloads carry no top-level event_type, so the Message shortcut filter doesn't match. Slack event subscriptions can't currently be pointed at an FYAI webhook directly.