Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Webhooks and APIs

Webhooks by Zapier: Catch Hook

Learn how Webhooks by Zapier turns any HTTP POST into a Zap trigger: the Catch Hook URL, test requests, response codes and a runnable receiver simulator.

Most Zapier triggers are built for one specific app: "New Row in Google Sheets", "New Email in Gmail". But what if your tool has no Zapier integration, or the event you need is not offered? Then you use a webhook. A webhook is simply a web address that waits for another program to send it a message. When the message arrives, your Zap starts.

In Zapier this is done with the built-in app Webhooks by Zapier. Its most used trigger event is Catch Hook. In this lesson you will learn how it works, what a request looks like, what Zapier answers, and the mistakes that cause "my Zap never fires". The Zapier product itself cannot run on this site, so the steps below describe the menus in words, and the code blocks are small stand-ins written in JavaScript that behave like the idea they teach. Each one is labelled.

What a webhook is, in one picture

An ordinary integration works by polling: Zapier asks the app every few minutes "anything new?". A webhook flips this around: the other system pushes an HTTP request to you the moment something happens. It is faster and uses no polling.

sequenceDiagram
    participant S as Your system
    participant Z as Zapier hook URL
    participant A as Zap actions
    S->>Z: POST /hooks/catch/... (JSON body)
    Z-->>S: 200 OK with a small JSON answer
    Z->>A: Run the Zap with the request data

The sender gets its answer immediately; the Zap runs after that.

Creating a Catch Hook trigger

In the Zap editor you set up the trigger like this:

  1. Choose the trigger app Webhooks by Zapier.
  2. Choose the event Catch Hook (other events are Catch Raw Hook and Retrieve Poll, covered below).
  3. Optionally set Pick off a Child Key if you only want one part of a nested payload.
  4. Zapier shows you a custom webhook URL. It looks like https://hooks.zapier.com/hooks/catch/<account id>/<hook id>/. Copy it into the system that should send events.
  5. Choose Test trigger. Zapier waits until one request arrives, then shows the fields it found.

That last step matters: Zapier learns the shape of your data from the sample request. If you test with an empty or incomplete sample, later steps will not offer you the fields you need. Always send a realistic example first.

Treat the hook URL like a password. Anyone who knows it can start your Zap, and Zapier does not check who sent the request. Section "Securing a hook" in Security and Access Control shows what to add.

What a Catch Hook accepts

Catch Hook accepts a POST (and also PUT or GET with query parameters) and understands three body formats:

Content type Example body How Zapier reads it
application/json {"email":"[email protected]"} Each key becomes a field
application/x-www-form-urlencoded email=a%40b.com&plan=pro Each pair becomes a field
query string on the URL [email protected] Each parameter becomes a field

If the data arrives in some other shape (XML, a signed text blob, a raw body you must hash), use Catch Raw Hook. It gives you the untouched body as one field plus the headers, and you parse it yourself with Code or Formatter steps.

Retrieve Poll is the third event. You give it a URL that returns JSON, and Zapier fetches it on its normal polling schedule. Use it when you can read data but cannot make the other system push it.

What Zapier answers

Zapier replies with a status 200 and a small JSON body containing a status of success, a request id and an attempt id. The important point is when: the reply is sent as soon as the request has been accepted, not after your Zap has finished. So a 200 tells the sender "received", never "your actions succeeded". If the sender must receive a custom answer, Zapier has a separate event for that (a trigger that waits for a response from the Zap); check your plan and the current documentation before relying on it.

A receiver you can run

Below is a stand-in, not Zapier code: a tiny function that behaves like a hook endpoint. It parses the three body formats, rejects bodies that are too large or have the wrong type, and returns what the next Zap step would see.

JS Stand-in: a Catch Hook receiver

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice how the query-string field source is merged with the body fields, and how a broken JSON body is refused. In the real product a malformed body produces an error on the sender's side, so the sender at least learns something went wrong.

Testing a hook without the sending app

You rarely need the real sender to test. Any tool that sends HTTP requests works: a terminal command, an API client, a browser form, or a script. A typical command line test looks like this (read-only example, you would run it on your own computer):

Terminal
curl -X POST "https://hooks.zapier.com/hooks/catch/123456/abcdef/" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","plan":"pro","amount":49}'

The ids in the URL above are made up. After the request, return to the editor and choose Find new records or run the test again: your sample appears with the fields email, plan and amount.

Planning the sample payload

Because the sample defines your fields, it helps to design the payload on purpose. Good habits:

  • Send flat, named fields when you own the sender: customer_email beats a nested array position.
  • Include an event id (order_id, event_id). You will need it for deduplication in Tables Lookup and Dedupe.
  • Include a timestamp in ISO 8601 (2026-03-14T09:30:00Z) so formatters can parse it.
  • Include every optional field in the sample, filled with a typical value. A field missing from the sample does not appear in later steps.

The next script is a stand-in checker that warns you about the problems above before you send a sample.

JS Stand-in: a sample payload checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common reasons a hook "does nothing"

  • The Zap is switched off. In the editor a test request is captured, but a published Zap only runs while it is turned On.
  • The sample was never captured. The Test step must show data before you continue.
  • Wrong method or content type. A GET with a body, or a JSON body with Content-Type: text/plain, will not be parsed as you expect.
  • Redirects. Some senders do not follow a 301. Use the exact https:// URL.
  • Hook URL changed. Creating a new Zap creates a new URL; the old sender keeps calling the old Zap.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. When does Zapier send the 200 reply to a Catch Hook request?

    The reply confirms receipt only. The actions run afterwards, so a 200 does not mean they succeeded.
  2. 2. Which event do you pick when the body is signed XML that you must verify yourself?

    Catch Raw Hook gives you the unparsed body and the headers, so you can parse or verify it yourself.
  3. 3. Why should the sample request in the editor contain every field you will need?

    Fields missing from the sample are not offered in later steps, so you would have to resend a better sample.

Summary

  • A webhook lets another system push an event to a Zap the moment it happens.
  • Catch Hook parses JSON, form-encoded and query-string data; Catch Raw Hook gives the raw body; Retrieve Poll fetches a URL on a schedule.
  • Zapier learns the fields from the sample request, so send a realistic, complete sample.
  • The 200 reply only says "received". Treat the hook URL as a secret.

Next: Webhook Payloads and Flattening