How to start a workflow from a webhook

A webhook is a message another service sends to a web address when something happens, for example a form service telling you a new order arrived. In TeleportHQ, you receive it with a workflow whose trigger is Webhook Received: copy the workflow's endpoint URL, publish your site, then paste the URL into the other service. Each request to that URL runs the workflow on your server, and later steps can use the request's data.

Before you start#

• Workflows are a web app feature. On a website, creating a workflow first asks you to enable web app features. See What are workflows?.
• Publish your web app at least once. The webhook URL only works on your published site. See How to publish a web app.
• If you only need store payments to be marked as paid, use the store's own payment webhook instead. See How to set up the payment webhook.

Steps#

This example receives new orders from an online form service and saves them to a bakery's Orders table.

1. Create the webhook trigger#

1. In the left sidebar, click Workflows, then click + (Add Workflow). Name it, for example New order from form service.
2. On the canvas, right-click the Page is Loaded trigger and choose Replace node type.
3. Point at Webhook, then click Webhook Received in the list beside the menu.
4. Click the new trigger to open its settings in the right panel. The panel says "Webhook workflows run entirely on the server."

2. Set up the endpoint#

1. Endpoint Path: keep the suggested path, or type your own after /api/, for example webhooks/new-order. The full path shows under the field.
2. HTTP Method: choose the method the other service sends: POST (the default), GET, PUT or DELETE.
3. Description: type a note, for example Form service new order webhook.
4. Next to Endpoint Path, click the copy button (tooltip Copy full URL). Once you've published, this copies your site's address plus the path, for example https://mybakery.com/api/webhooks/new-order. It uses your custom domain when you have one.

3. Secure the webhook (recommended)#

1. Set Verify Signature to Enabled.
2. Under Signature Algorithm, choose what the service uses: HMAC SHA-256, Stripe (v1), PayPal (v1) or Custom.
3. Under Signature Header, enter the header name the service sends, for example stripe-signature for Stripe.
4. Under Signing Secret, paste the secret from the service's webhook settings. It is stored as a project secret.
5. Optional: under Expected Headers, add a header name (and value) that every real request must include.

4. Add steps and publish#

1. Click the round + under the trigger (Add node) and add the steps, for example Create Item from Data.
2. Fill the fields from the request data. The trigger's data, Webhook Request, includes Request Body, Request Headers, Query Parameters, HTTP Method, Request Path and Signature Valid. See How to use data from one workflow step in the next.
3. Publish your site.
4. In the other service's webhook settings, paste the URL you copied.

Check that it worked#

• The workflow card in the Workflows panel shows a Webhook badge.
• Send a test event from the other service (most services have a "send test" button), then check the result, for example a new row in the Orders table.

TeleportHQ has no log of past runs for webhook workflows, so you can't see which requests arrived or whether a run failed. The Test runs tab only lists tests of steps you ran in the editor. To check a live run, look at its result, for example the new record. Many services also list the requests they sent and the answer they got in their own webhook settings.

Troubleshooting#

Copy full URL copies only a path like /api/webhooks/… Your site has no live address: it hasn't been published yet, or it was taken offline with Unpublish. Publish, then copy the URL again.

The other service shows an error answer Your published site answers each webhook request. The service's webhook settings usually show the answer:

• "Method not allowed": the service uses another HTTP method than the one you chose. Change HTTP Method and publish again.
• "Missing required header: …" or "Invalid header value for: …": a request didn't include an Expected Headers entry. Check the header name and value.
• "Invalid signature": the Signing Secret, Signature Algorithm or Signature Header doesn't match the service's settings.
• "This delivery is already being processed": the service sent the same message again while the first one was still running. It's turned away for a moment and the service tries again later.
• "Webhook processing failed": a step failed. Test the steps in the editor, and add steps to the Workflow Error box to be told when this happens.

"Webhook workflows run on the server and cannot use client-side nodes" A webhook has no visitor, so steps from Navigation, Element, Forms, URL, State, Browser, Storage, Audio and Toast can't be used. Use server steps such as Data, Email, HTTP Request or Integrations.

"Remove client-side nodes before switching to a webhook trigger" or Cannot Switch to Webhook Trigger The workflow already contains browser-only steps. Delete them, then replace the trigger again.

"These steps need a browser, and this workflow runs on the server when a webhook arrives." You tried to paste browser-only steps into a webhook workflow. Paste server steps only.

Good to know#

• Your published site answers a webhook request after the workflow's steps finish, with a short "received" message. Requests with the wrong method, a missing expected header or an invalid signature are refused before any step runs.
• Changing the Endpoint Path changes the URL. Update it in the other service and publish again.
• Add steps to the Workflow Error box to be told when a webhook workflow fails, for example with a Slack message.