How to Trigger a Workflow From a Webhook
What a Webhook Actually Is
A webhook is an HTTP request that one system sends to another when an event occurs. Instead of your workflow constantly checking Stripe for new payments (polling), Stripe sends your workflow a notification the moment a payment succeeds (pushing). The notification is an HTTP POST request containing a JSON payload with all the relevant data about the event.
The webhook model has three parts: the sender (the external system that generates events), the receiver (your workflow's endpoint URL), and the payload (the JSON data the sender includes with each request). Your workflow is the receiver. You give the sender your workflow's URL, tell it which events to send, and the sender does the rest.
This push model has two major advantages over polling. First, speed: your workflow starts within milliseconds of the event instead of waiting for the next poll interval. A customer who pays at 10:00:03 gets their confirmation email at 10:00:05 instead of 10:15:05. Second, efficiency: your system does zero work between events. No wasted API calls checking for changes that have not happened yet.
Setting Up a Webhook Trigger Step by Step
In your workflow builder, add a webhook trigger node as the first step. The platform generates a unique URL for this workflow, something like https://hooks.yourplatform.com/wf/abc123. This URL is what you will give to the external system. Every POST request sent to this URL triggers one execution of your workflow.
Copy this URL and keep it ready. You will paste it into the sending system's webhook configuration.
In the external system (Stripe, Shopify, Typeform, Calendly, GitHub, or any tool that supports webhooks), find the webhook or integration settings. This is usually under Settings, Developer, or Integrations.
Paste your workflow's URL as the destination. Select which events should trigger the webhook. Most systems let you choose specific event types: payment.succeeded, order.created, form.submitted, booking.confirmed. Select only the events your workflow needs. Receiving unnecessary events wastes resources and complicates your workflow's logic.
Common webhook configuration locations by platform:
- Stripe: Dashboard > Developers > Webhooks > Add endpoint
- Shopify: Settings > Notifications > Webhooks > Create webhook
- Typeform: Form > Connect > Webhooks > Add webhook
- Calendly: Account > Integrations > Webhooks > Create webhook
- GitHub: Repository > Settings > Webhooks > Add webhook
- HubSpot: Settings > Integrations > Webhooks > Configure
- WooCommerce: Settings > Advanced > Webhooks > Add webhook
After configuring the sender, trigger a test event (make a test purchase, submit a test form, create a test booking). Your workflow receives the webhook and logs the raw payload. Open the execution log and examine the JSON structure.
A Stripe payment webhook payload looks something like this in structure: it contains an event type, a data object with the payment amount, currency, customer email, customer name, payment status, and metadata. A form submission payload contains the form ID, submission timestamp, and key-value pairs for each form field.
Map each field you need to a workflow variable. Your email action needs the customer's email address, so note the JSON path to that field (e.g., data.customer.email). Your database action needs the amount, so note that path too (e.g., data.amount). Variable mapping tells the workflow where in the payload to find each piece of data it needs for subsequent steps.
An unsecured webhook URL can be triggered by anyone who knows (or guesses) the URL. This means someone could inject fake events into your workflow, potentially creating bogus orders, sending unauthorized emails, or corrupting your database. Three approaches to webhook security:
- Signature verification: The sender includes a cryptographic signature in the request header, calculated from the payload and a shared secret. Your workflow recalculates the signature and compares. If they match, the request is authentic. Stripe, GitHub, Shopify, and most major platforms support this. It is the strongest option.
- Shared secret in URL: Append a random token to your webhook URL: https://hooks.yourplatform.com/wf/abc123?secret=my-long-random-string. Your workflow checks that the secret parameter matches. This is simpler but less secure than signature verification.
- IP allowlisting: Only accept webhook requests from the sender's known IP addresses. Most platforms publish their webhook source IPs. This works but requires maintenance when the sender's IPs change.
At minimum, use the shared secret approach. For workflows that handle payments, personal data, or business-critical actions, implement signature verification.
After securing the endpoint and mapping the data, trigger real events (not just test payloads) and verify the complete workflow runs correctly. Make an actual purchase with a test credit card. Submit the actual form on your website. Book an actual appointment with a test calendar.
Check that:
- The workflow triggers within 1-2 seconds of the event
- All data fields are correctly extracted from the payload
- Each action step uses the correct data (email goes to the right address, database record has the right values)
- Conditions evaluate correctly based on the real data format
- Error handling catches any unexpected payload variations
Handling Different Event Types
Many external systems send multiple event types to the same webhook URL. Stripe can send payment.succeeded, payment.failed, customer.created, invoice.paid, and dozens of other events. If your workflow only needs to act on payment.succeeded events, you need to filter the others.
Add a condition node right after the webhook trigger that checks the event type field. If the event type matches what your workflow handles, continue execution. If it does not match, end the workflow immediately. This prevents your workflow from running unnecessary steps (or worse, taking wrong actions) on event types it was not designed for.
For workflows that handle multiple event types differently, use a switch condition after the trigger. Each event type gets its own branch with its own action sequence. A single workflow can handle payment successes (send confirmation), payment failures (send retry notification), and subscription cancellations (trigger retention sequence) by routing each event type to the appropriate branch.
Webhook Reliability: What Happens When Things Fail
Webhook delivery is not guaranteed to succeed on the first attempt. Your workflow endpoint might be temporarily unreachable. Your platform might be deploying an update. A network issue might drop the connection. Most webhook senders handle this with automatic retries.
Stripe retries failed deliveries up to 3 times over several hours. Shopify retries up to 19 times over 48 hours. GitHub retries once after 10 seconds. Each platform has its own retry policy, documented in their webhook guides.
Your workflow needs to handle retries gracefully. The most important rule: design for idempotency. If the same webhook is delivered twice (because the sender retried after a timeout even though the first attempt actually succeeded), your workflow should not create duplicate records, send duplicate emails, or process the same payment twice.
Techniques for idempotent webhook handling:
- Check for duplicates: Before creating a record, check if a record with the same unique identifier (order ID, payment ID, submission ID) already exists. If it does, skip the creation step.
- Use the event ID: Most webhook payloads include a unique event ID. Store processed event IDs in your database. Before processing a new webhook, check whether that event ID has already been processed.
- Make actions safe to repeat: Use "upsert" database operations (insert if new, update if exists) instead of plain inserts. This way, a duplicate webhook updates the existing record instead of creating a second one.
Debugging Webhook Issues
When a webhook workflow is not working, the problem is almost always in one of these four places:
The webhook is not being sent. Check the sending platform's webhook logs. Most platforms show a delivery log with status codes. If you see no delivery attempts, the webhook is misconfigured in the sender (wrong event type selected, webhook disabled, or incorrect URL).
The webhook is sent but your endpoint returns an error. Check your workflow platform's execution logs for the incoming request. If the webhook arrived but the workflow failed, the error is in your workflow logic (wrong variable path, failed action, unhandled data format).
The payload format changed. External systems occasionally update their webhook payload structure. A field that was at data.customer.email might move to data.customer_details.email_address. If your workflow suddenly stops extracting data correctly, compare the current payload to the format you originally mapped.
Authentication is rejecting valid requests. If you added signature verification or IP filtering, check that the configuration matches what the sender provides. A common mistake is copying the signing secret incorrectly or forgetting to update IP allowlists when the sender adds new servers.
Common Webhook Sources for Business Workflows
Payment and billing: Stripe, PayPal, Square, and Braintree send webhooks for successful payments, failed charges, subscription changes, refunds, and disputes. These trigger order fulfillment, receipt delivery, dunning sequences, and accounting updates.
E-commerce: Shopify, WooCommerce, BigCommerce, and Magento send webhooks for new orders, inventory changes, customer registrations, and cart abandonments. These trigger fulfillment workflows, inventory alerts, and customer communication sequences.
Forms and surveys: Typeform, JotForm, Google Forms (via Apps Script), and Gravity Forms send submission data as webhooks. These trigger lead capture, customer onboarding, feedback processing, and data entry workflows.
Scheduling: Calendly, Acuity, and Cal.com send webhooks when appointments are booked, rescheduled, or cancelled. These trigger confirmation sequences, reminder workflows, and no-show follow-ups.
CRM and sales: HubSpot, Salesforce, and Pipedrive send webhooks when deals progress, contacts are updated, or lifecycle stages change. These trigger sales notifications, pipeline updates, and handoff workflows.
Development: GitHub, GitLab, and Bitbucket send webhooks for code pushes, pull requests, issues, and deployments. These trigger CI/CD pipelines, notification workflows, and project management updates.