Skip to main content
A webhook trigger gives a workflow its own URL. Any system that can send an HTTP request, such as your backend, a CI job, a form tool, or another SaaS product, can start the workflow by posting JSON to that URL with the trigger’s bearer token. The request body becomes the workflow’s input.
Webhook triggers are the secure, preferred way to let an outside system start work in Major. Every call must carry the trigger’s credential, and calls without it are rejected. Webhook routes on an app are public and unauthenticated, so use them only when a service must post raw payloads to your app and can’t send a credential.

​
Example requests

  • “Give our backend a URL it can call with an order id to start the refund review workflow.”
  • “Add a webhook trigger to the lead-routing workflow that takes an email and a company name.”
  • “Let our CI pipeline start the release-notes workflow when a deploy finishes.”

​
How a webhook trigger is defined

A webhook trigger has an id, the type webhook, and an optional label and input. It has no config, and its URL and credential never appear in the definition.

​
Getting the URL and credential

Each webhook trigger has one URL and one bearer token. The token is shown once, so copy both into the system that will call the workflow, such as its secrets manager, before you close the dialog.
1

Add the trigger

In the workflow editor, add a trigger and choose Webhook. Major creates the URL right away and shows the URL and token. Copy both, confirm you’ve saved the token, and click Done.If the trigger was added in JSON, through the Platform Agent, MCP, or the CLI, its URL is created when you publish. Open the workflow in the editor afterwards and click View credential on the trigger to generate and reveal the token.
2

Publish

The URL doesn’t accept calls until the workflow is published. Before that, calls are rejected.
3

Call the URL

Send a POST with the token in the Authorization header.
Only people who can edit the workflow can view a credential. The token is never shown again, and Major never includes it in chat, MCP results, or the workflow file. If you lose it, remove the trigger, publish, and add it again. That creates a new URL and token.

​
Calling the webhook

  • The body must be JSON, sent with Content-Type: application/json, and at most 1 MB.
  • A successful call returns 200 after the run has been created.
  • An unknown URL, a missing or wrong token, or an unpublished trigger all return 404, so the response never reveals whether a trigger exists.
  • A body that isn’t valid JSON returns 400, and a body over 1 MB returns 413.
Use the exact URL shown in the editor. The <webhook-id> in it is generated by Major and is not the trigger’s id in the definition. Each call starts one run of the published version, which appears in the workflow’s run history.

​
Shaping the input

By default, the JSON body becomes trigger.input as is, so the call above gives the workflow trigger.input.order_id and trigger.input.amount. The body must be a JSON object in this case. To pick or rename fields, set input on the trigger. Each value is a JSON literal or a { "$expr": "..." } CEL expression, and expressions can only read the body, as event.json:
If the workflow has an input_schema, the input is validated against it. When the projection fails or the input doesn’t validate, the call still returns 200, and the run is recorded as failed with the reason. See State and input.

​
Removing a webhook

Removing a published webhook trigger takes effect when you publish: the URL keeps working until then, and publishing retires it and revokes its token. Removing a trigger that was never published retires it immediately. The credential acts on behalf of the workflow’s publisher at the time it was created. If that person loses access to the workflow or leaves the organization, calls are rejected.

​
Next steps

Connector events

Start a workflow from events in services you’ve connected.

State and input

Validate and use the webhook’s input.