---
title: "Create your first webhook - Workflow Webhooks"
description: "Step-by-step: create a webhook endpoint, authenticate it, map your payload and connect it to a Shopify Flow workflow."
canonical: "https://docs.workflow-webhooks.app/getting-started"
---

# Create your first webhook

This walks you from an empty app to a Shopify Flow workflow that runs when your own
system says so. About ten minutes.

> [!NOTE]
> Workflow Webhooks needs **Shopify Flow** installed. It is free from Shopify and is what
> actually runs your automation - this app is the bridge that lets outside systems start it.

## 1. Create a webhook

**Webhooks -> Create webhook**. Give it a name you will recognise later ("Wallet card
reminder", "Contact form"), pick a template if one matches your tool, and save.

You now have a **webhook URL** ending in a short code, for example
`https://.../webhook/ab12cd34`. That URL is the endpoint your system POSTs to.

## 2. Choose how callers prove who they are

Open the webhook and pick an authentication method. See [Authentication](https://docs.workflow-webhooks.app/authentication.md) for the
full comparison - the short version:

- **Static token** - right for almost everyone. Press the generate button, copy the token,
  send it in the `X-Api-Key` header.
- **HMAC SHA-256** - for senders that sign their requests (Stripe, GitHub and similar).
- **None** - testing only. Anyone with the URL can fire your workflow.

## 3. Tell us which fields you care about

Under **Advanced Settings**, map up to four fields out of your JSON payload. If your
system sends:

```json
{ "customer": { "email": "someone@example.com" }, "orderId": "1001" }
```

map `fieldOne` to `orderId` and `fieldTwo` to `customer.email` - nested paths use dots.
Full detail in [Payload mapping and Flow variables](https://docs.workflow-webhooks.app/payload-mapping.md).

## 4. Send a test request

```bash
curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token" \
  -d '{"orderId":"1001","customer":{"email":"someone@example.com"}}'
```

Open **History**. You should see the call with its status, headers and payload. If it is
not there, [History and troubleshooting](https://docs.workflow-webhooks.app/history-and-troubleshooting.md) lists every rejection reason.

## 5. Build the Flow workflow

In **Shopify Flow**, create a workflow starting with the **Webhook Trigger** trigger.

1. Add the trigger and click **Record Events**.
2. Come back here, open the invocation in **History**, and press **Replay**. Flow now has a
   real example payload to work with - much easier than guessing field names.
3. Add a **Condition**: `Webhook ID` equals your webhook's id (shown on the webhook page).
   Every Webhook Trigger workflow receives events from *all* your webhooks, so this
   condition is what makes the workflow respond to only this one.
4. Add your actions, using `{{fieldOne}}` to `{{fieldFour}}`.
5. Turn the workflow on.

> [!IMPORTANT]
> Step 3 is the one people skip. Without the Webhook ID condition, every webhook you own
> will run this workflow.

## 6. Go live

Point your real system at the webhook URL. Watch the first few calls in **History** to
confirm they arrive and succeed.

If your sender retries on timeout, turn on [Duplicate delivery protection](https://docs.workflow-webhooks.app/duplicate-delivery.md) so a retry cannot
run your workflow twice.