From f2175b1fbae490bb9712dbdf96b5261c50767026 Mon Sep 17 00:00:00 2001 From: "Elias W. BA" Date: Fri, 4 Sep 2026 22:36:12 +0000 Subject: [PATCH] Document webhook custom URLs The Webhook Event Triggers section never said what a webhook's URL looks like or where to find it, so there was nothing to extend: a reader had no way to learn that a trigger can now answer on a name you choose as well as on its id. Covers both URL shapes, what a name may contain, that names are unique per project, and that renaming or removing one breaks it with no redirect. That last one is the trap worth the warning, since the sending system has to be updated first. --- docs/build/triggers.md | 46 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/build/triggers.md b/docs/build/triggers.md index f447f1cbc131..2c173fbc22a1 100644 --- a/docs/build/triggers.md +++ b/docs/build/triggers.md @@ -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 +changes. It looks like `https://app.openfn.org/i/`. + +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//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 +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 +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, +because their URLs differ by project id. + +:::warning There's no redirect + +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 +`/i/` 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