Webhook Engine, explained simply.

A complete guide for people who do not write code. Every feature, every step, in plain English. (Pro) marks anything that needs the paid add-on — see the pricing page. This is Part 1, covering setup and sending. The reference and troubleshooting half is on a second page.

What it does · Words you will see · Installing · Your first form · How the answer comes back · Callback mode · Where the answer appears · Chat mode · Saving a reply · Reference & troubleshooting →

Words you will see in this guide

Read this once and the rest will make sense.

Your first form, step by step

Step 1 — Get a web address from your platform

1. In your automation platform, create a new workflow.
2. Add a trigger step that receives information from the web. In n8n this is a Webhook node; in Make it is Custom webhook; in Zapier it is Webhooks by Zapier → Catch Hook.
3. Set it to accept POST.
4. Copy the web address it gives you.

Step 2 — Create the form

1. Go to Webhook Engine → Forms.
2. In Form ID, type a short name using lowercase letters, numbers and dashes, such as ask-health. This cannot be changed later.
3. In Label, type a heading to show above the form. Optional.
4. In Webhook URL, paste the address from Step 1.
5. In Fields, describe the boxes you want, one per line.
6. In Button text, type what the button should say.
7. In Waiting message, type what shows while your workflow is thinking.
8. Click Add form.

question | Your question | textarea | required
email    | Your email address | email

Step 3 — Check it can reach your workflow

1. Click Test webhook on the same screen.
2. The plugin sends a real, clearly-marked test with sample values.
3. You should see a success message, and the test should appear in your workflow’s history.

A test is marked as a test and carries no return address. If you are using callback mode, a test cannot be replied to. That is expected — use it to confirm the connection, then test the reply from a real page.

Step 4 — Put the form on a page

1. Create or edit a page.
2. Add the shortcode where you want the form:
3. Save the page as a draft first.
4. Click Preview and try the form yourself.
5. Publish when you are happy.

Step 5 — Send an answer back

In your workflow, send back a small piece of JSON containing the answer.

{ "reply": "Yes, the clinic is open from 8am to 4pm on weekdays." }

The word reply is not special. The plugin understands many names for the same thing — see field names. Your answer can use Markdown for formatting.

Callback mode, in detail

What problem it solves

When your site sends a question to your workflow, it normally waits on the open line for the answer, like staying on hold on the phone. That has two problems.

1. Some platforms cannot answer on that line at all. They accept your message and hang up. There is nothing wrong with them — many are built that way.
2. Nobody can stay on hold forever. Your site will not wait longer than 30 seconds, because waiting ties up part of your server. A workflow that takes two minutes cannot possibly answer in time.

Callback mode fixes both. Instead of staying on hold, your site says: here is my return address, send the answer when you have it. Then it hangs up. The visitor still sees the waiting message. Behind the scenes their browser quietly checks back every couple of seconds until the answer arrives.

Sending a message to a web address is something every automation platform can do. That is why this works everywhere.

How to turn it on

1. Go to Webhook Engine → Forms and open your form.
2. Set Response handling to Callback.
3. Optionally set Callback deadline — how many seconds the visitor waits before being told nothing arrived. Leave it empty to use the site-wide value.
4. Click Save form.

There is nothing to configure on your automation platform.

What your workflow receives

Every submission now carries three extra items alongside the normal fields.

{
  "source": "form",
  "endpoint": "ask-health",
  "fields": { "question": "Is the clinic open?" },

  "return_url": "https://example.com/wp-json/webhook-engine/v1/return/<id>?token=<token>",
  "request_id": "<id>",
  "deadline": "2026-01-01T12:02:00+00:00"
}

What to send back

Send a normal web message (a POST) to that return_url. You have two options, and both work.

Option one — just send text

Send your answer as plain text, with no structure at all.

Yes, the clinic is open from 8am to 4pm on weekdays.

The whole message becomes the reply. You do not need to build any JSON. If your platform can only send text to an address, you are finished.

Option two — send JSON

If you prefer structure, the plugin looks for your answer under any of these names:

body · markdown · content · text · answer · reply · message · output · article · description · summary

So all of these mean exactly the same thing:

{ "reply":  "Yes, we are open." }
{ "answer": "Yes, we are open." }
{ "text":   "Yes, we are open." }
{ "output": "Yes, we are open." }

The reason there are so many names is simple: whatever your AI step already calls its output, it very likely matches one of them. You should not have to add a step just to rename a field.

Name matching is forgiving. Capital letters, underscores, dashes and spaces are ignored. postTitle, post_title and "Post Title" are all the same name.

Wrappers are removed automatically, up to four layers deep. All of these work:

{ "reply": "Yes, we are open." }
{ "data":   { "body":   "Yes, we are open." } }
{ "result": { "output": { "text": "Yes, we are open." } } }
[ { "message": "Yes, we are open." } ]

Wrapper names removed: data, payload, result, results, json, output, item, items, record, fields, attributes, object — plus a list containing exactly one item.

You can add a heading. Include a title and it appears above the answer.

{ "title": "Opening hours", "body": "We are open 8am to 4pm on weekdays." }

If nothing matches, it still works. Send something with no recognised answer field and the plugin shows it as a neat labelled table instead of failing. That is genuinely useful for lookups that return facts rather than prose.

{ "city": "Lagos", "temperature": 21, "humidity": 60 }

Keeping the password out of the address

The return address has a one-time password in it, after ?token=. Web servers often record addresses in their logs, so if that bothers you, move it:

1. Remove everything from ?token= onwards.
2. Send the token as a header named X-Webhook-Engine-Token instead.

Both work identically. The address version is the default only because it works with the simplest possible sender.

Categories and tags

The answer can carry more than the text itself. Categories and tags come back as small labels above and below the answer — and if you have turned on draft post creation, they are applied to the post as real categories and tags.

{
  "title":      "Opening hours",
  "body":       "We are open 8am to 4pm on weekdays.",
  "categories": ["Clinic"],
  "tags":       ["hours", "reception"]
}

Category names understood: categories, category, cats, sections, topics. Tag names understood: tags, tag, keywords, terms, labels.

The shape is forgiving. A proper list and one plain line with commas mean the same thing — ["hours", "reception"] or "hours, reception".

This is the setup for “the form writes a post for me.” A visitor describes what they want, your AI step writes it, and the answer comes back carrying a title, the article itself, and the categories and tags to file it under. Turn on Draft post creation on the form (Pro) and the whole thing lands in your drafts, ready for you to review. See Turning replies into draft posts in Part 2.

Everything except the answer itself is optional. Leave out the title, the categories, the tags — or all three — and nothing changes: no empty heading appears and no stray labels are added. Send only what you have.

Telling the visitor something went wrong

If your workflow fails, do not leave the visitor waiting. Send this instead:

{ "status": "error", "error_message": "The document search timed out." }

The visitor immediately sees your normal failure wording. Your message is not shown to them — it is recorded under Settings → Recent send problems, where only administrators can see it. That split is deliberate: error messages often contain server names and internal addresses, which should never appear on a public page.

The deadline

• Minimum 15 seconds, maximum 10 minutes, normally 120 seconds.
• Set it site-wide under Settings, or per form.
• Leave the per-form box empty to inherit the site-wide value.

Unlike the Request timeout setting, a long deadline here costs your server nothing. The submission has already finished; the visitor’s browser is simply checking back. So you can be generous.

Tip: set the deadline comfortably above your workflow’s slowest realistic run. If it usually takes 40 seconds, set 120, not 45.

What the visitor sees while waiting

• Your waiting message, with a spinner.
• After 5 seconds, a counter showing how long it has been.
• Their typed text stays in the box, and the button is disabled so they cannot submit twice.

When the answer arrives it appears in place and the button becomes available again. Their typed text stays in the box — a question box behaves like a search box, not a contact form, so they can adjust the wording and ask again. Only Send only mode clears the form, because there is no reply to compare against. If the deadline passes, they see “No reply arrived in time. Please try again.” with their text preserved.

Retries are safe

If your platform sends the same answer twice — many retry automatically — the second is politely accepted and ignored. The visitor’s answer is never replaced, and your platform sees a success so its own run is not marked as failed.

Common mistakes

Does callback work with everything else?

Chat mode

Turning on Conversation mode changes a form into a chat. Messages appear as bubbles, and each new message sends the whole conversation so far to your workflow — so it can answer with context, remembering what was said earlier.

Setting it up

1. Open your form under Webhook Engine → Forms.
2. Tick Conversation mode.
3. Optionally type a Welcome message — a first message from your assistant.
4. Click Save form.

The first visible field becomes the message box. Other visible fields are ignored in chat mode. Hidden fields are still sent every time, which is handy for routing.

{
  "fields": { "question": "What about for children?" },
  "conversation": {
    "history": [
      { "role": "user",      "content": "Is the vaccine available?" },
      { "role": "assistant", "content": "Yes, as of..." }
    ]
  }
}

Things to know

• Nothing is stored on your site. The conversation lives only in the visitor’s browser and disappears when they reload. For a site answering sensitive questions, that is a feature.
• The history sent to your workflow is capped: the last 20 messages, 4,000 characters each, 20,000 in total.
• Enter sends. Shift + Enter starts a new line.
• Answers appear all at once when ready, not word by word.
• Callback mode and Draft post creation are not available in chat mode.

The Enter key on ordinary forms

Every non-chat form has an Enter key setting:

• Auto — if the form is a single large box, Enter sends it and Shift+Enter adds a line. Multi-field forms are left alone.
• Enter always submits — useful for a search-box style layout.
• Enter never submits — use this when visitors write longer text.