Skip to content

Document webhook custom URLs #849

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
elias-ba wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document webhook custom URLs #849

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions docs/build/triggers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,52 @@ Trigger by adding authentication, head over to our
Learn how a workflow's initial `state` gets built from a webhook trigger
[here](../jobs/state#webhook-triggered-runs).

### Webhook URLs

Every webhook trigger answers on a URL built from its own id, and that URL never

@josephjclark josephjclark Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is "answers" the right word here? Is that consistent with our other docs? Strikes me as odd. Useed throughout this section

changes. It looks like `https://app.openfn.org/i/<trigger-id>`.

You can also give a trigger a name of your own. It then answers on a second URL,
built from your project's id and the name you chose, like
`https://app.openfn.org/i/<project-id>/et-emr-facility-001`.

Both URLs reach the same trigger. Naming one never replaces the default, so
anything already posting to the default URL keeps working.

Names are useful when you know what an endpoint should be called before the
workflow exists. If you're connecting the same system at a hundred sites, you
can generate the URLs from your list of site names rather than copying them out
of the app one at a time.

To add one, open the trigger and click **Add custom URL**. You type only the

@josephjclark josephjclark Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You have to do a bit more than that in the app right now:

  • Go into draft mode (if you have experimental features on, but maybe soon for everyone)
  • Click the trigger
  • Hit Edit
  • Hit Next
  • Now you can Add Cyustom URL

Its not intuitive so all this needs documenting fully

@elias-ba elias-ba Sep 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wait this doesn't need experimental mode at all. This feature is accessible to everyone

last segment of the address. The rest is fixed, and sits beside the field as
plain text. A name can use lowercase letters, numbers, hyphens and underscores,
up to 255 characters. It can't be a UUID, because OpenFn reads those as trigger

@josephjclark josephjclark Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the UUID thing true? The URL already includes the project if you're using a name, so why would a UUID be a problem?

ids.

A name has to be unique within a project, and OpenFn warns you as you type if
another workflow has already taken the one you're entering. A workflow that's
disabled still holds its name. Two different projects can use the same name,

@josephjclark josephjclark Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This last sentence is redundant (We just said a name has to be unique within a project)

because their URLs differ by project id.

:::warning There's no redirect

@josephjclark josephjclark Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't like the title of this. Maybe "There's no redirect on edit" is a bit better?


Renaming or removing a custom URL breaks it. Once you save, requests to the old
address get a `404`, so update the system sending the data first. The

@josephjclark josephjclark Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add "default": The default /i/ URL is unaffected. (maybe instead of the path?)

`/i/<trigger-id>` URL is unaffected.

:::

Changing a trigger from webhook to cron removes its custom URL, and changing it
back doesn't restore it.

[Webhook authentication](../manage-projects/webhook-auth.md) is attached to the
trigger rather than to an address, so it covers both URLs.

You can also set a name outside the app, as `custom_path` on a webhook trigger
in [project.yaml](/documentation/sync) or through the
[Workflows API](../build/workflows-api.md).

## **Webhook Trigger Responses**

When a workflow is triggered via a webhook, OpenFn can respond to the calling
Expand Down