Webhook Engine: reference & troubleshooting.
The second half of the guide. If you are setting up your first form, start with Part 1. (Pro) marks anything needing the paid add-on.
Bringing information in · Posts and pages · Draft posts (Pro) · Your existing form · Making it look right · When something goes wrong · Security software · Shortcode reference · Field names · Keeping your site safe · FAQ · Glossary
Bringing information into your site
This direction works the other way round: your platform sends information whenever it likes, and your site displays it.
Step 1 — Turn the door on
The plugin refuses all incoming information until you set a password. This is deliberate.
- Go to Webhook Engine → Settings.
- Find Inbound shared secret.
- Type a long random password — at least 16 characters.
- Click Save Changes.
- Copy the Endpoint URL shown just above it.
Common mistake
Leaving the secret empty. Nothing will arrive and it will look broken. It is not broken — it is locked.
Step 2 — Send something
Have your workflow send a POST to that address, with a header named X-Webhook-Engine-Secret containing your secret, and a body like this:
{ "channel": "health-news", "title": "New clinic opening in Kano", "body": "## Opening times\n\nThe clinic opens on **Monday**." }
channel is just a label you invent — a named stream. Channels create themselves the first time something arrives. Leave it out and it goes to a channel called default.
Step 3 — Show it on a page
Immunisation drive reaches 12,000 children
Round three complete
The third round of the childhood immunisation drive closed on Friday, with mobile teams reaching 12,000 children across four local government areas.
What was delivered
- Measles-rubella second dose
- Oral polio vaccine
- Vitamin A supplementation
Coverage in the two hardest-to-reach wards rose from 61% to 88%. Planning for round four begins next month.
Immunisation drive reaches 12,000 children
Round three complete
The third round of the childhood immunisation drive closed on Friday, with mobile teams reaching 12,000 children across four local government areas.
What was delivered
- Measles-rubella second dose
- Oral polio vaccine
- Vitamin A supplementation
Coverage in the two hardest-to-reach wards rose from 61% to 88%. Planning for round four begins next month.
Cold chain audit clears 18 of 20 facilities
Audit summary
The quarterly cold chain audit visited 20 primary health centres. Eighteen met the temperature-log standard for all 90 days reviewed.
Two sites failed on generator downtime and have been scheduled for solar refrigerator installation before the next round.
Immunisation drive reaches 12,000 children
Round three complete
The third round of the childhood immunisation drive closed on Friday, with mobile teams reaching 12,000 children across four local government areas.
What was delivered
- Measles-rubella second dose
- Oral polio vaccine
- Vitamin A supplementation
Coverage in the two hardest-to-reach wards rose from 61% to 88%. Planning for round four begins next month.
The first shows the most recent item, the second shows a list, and the third updates itself every 30 seconds without a reload. Full options are in the shortcode reference.
How much is kept
Each channel remembers a set number of recent items — 10 by default, adjustable from 1 to 50 under Settings → Payloads kept per channel. Older items drop off automatically. Any posts already created from them are unaffected.
Turning what arrives into posts and pages
- Go to Webhook Engine → Channels.
- In Add a rule, choose the Channel. You may name one that does not exist yet.
- Choose whether to create a Post or a Page.
- Choose a Status: Draft (always available), Pending review (Pro), or Publish immediately (Pro).
- Choose an Author — a real user allowed to write posts.
- For pages only, optionally choose a Parent page.
- Optionally choose a Default featured image.
- Click Add rule.
Strong recommendation
Start with Draft. Review a few, then switch to automatic publishing only once you trust the workflow. Automatic publishing means your secret alone can put content live on your site.
| In the message | Becomes |
|---|---|
title | The post title |
body | The post content, with Markdown formatted properly |
categories | Attached to existing categories only. Unknown names are skipped. |
tags | Attached, and created if they do not exist. |
| An image field | The featured image |
Duplicates are prevented automatically: the same channel, title and content will never create a second post, so a retry cannot double-publish.
Featured images
image_id— the ID of something already in your Media Library. Free, and the safest.image_base64— the image data sent directly. (Pro), and needs Inline image data switched on. Best when an AI generates the picture.image— a web address to download from. (Pro), and only from hosts you list under Allowed image hosts. Empty by default, so this is off until you allow a host.- The rule’s default image — used when nothing else is supplied.
Every image is checked to confirm it really is a JPEG, PNG, GIF or WebP by examining the file itself, not by trusting its name. Oversized images are skipped and the post is still created.
Turning replies into draft posts (Pro)
This works the other way round: it saves the answers your workflow gives to form submissions.
- Open a form under Webhook Engine → Forms.
- Scroll to Draft post creation.
- Tick to enable it, and choose the post type, status, author and default image.
- Click Save form.
- Works with Wait for and show the reply and with Callback, with no extra setup in either case.
- Not available in chat mode, because every chat message is an answer and you would drown in drafts.
- Identical answers never create a second post.
Using a form you already have
If you already have a form and do not want to rebuild it, you can hand its submissions to Webhook Engine. This step needs someone comfortable editing HTML.
<form data-wengine-bridge
data-wengine-endpoint="ask-health"
data-wengine-response="#my-answer">
<input type="text" name="question" />
<button type="submit">Ask</button>
</form>
<div id="my-answer"></div>
data-wengine-endpointchooses which saved form’s settings to use — including its response mode, so callback works here too. The web address always stays on the server; the browser never sees it.data-wengine-responseis optional. Without it, the answer appears just after the form.
Important
Do not add this to forms built by WPForms, Gravity Forms, Contact Form 7 or a page builder. Those run their own submission code and the two will fight.
Making it look right
Without writing any code
| Setting | What it does |
|---|---|
| Accent colour | Tints the button and the form’s border. |
| Layout | Stacked puts labels above boxes. Inline puts everything on one row, like a search box. |
| Border | Match the accent colour, pick a custom colour, or remove it. |
| Chat area colour | The background behind chat messages. |
| Extra CSS class | For a designer to target this one form. |
None of these change what is sent or received. They are purely visual.
With CSS
Go to Appearance → Customize → Additional CSS.
/* Remove the card, leaving plain fields */
.wengine-form { border: none; padding: 0; background: transparent; }
/* Change just the border colour */
.wengine-form { border-color: #cccccc; }
/* Target one form using its Extra CSS class */
.wengine-form.my-form { border-radius: 0; }
Useful class names: .wengine-form, .wengine-submit, .wengine-response, .wengine-thread, .wengine-bubble-user, .wengine-bubble-assistant, .wengine-items, .wengine-item.
When something goes wrong
What visitors see
| What happened | What they see |
|---|---|
| Your workflow was too slow | This is taking longer than usual. Please try again in a moment. |
| Your workflow could not be reached | The service is temporarily unavailable. |
| Your workflow answered but sent nothing | That went through, but no reply came back to show. |
| A callback deadline passed | No reply arrived in time. Please try again. |
Their typed text is always kept so they can retry without retyping.
Adding your own message
- Go to Settings → If a send fails, add for the whole site, or set it per form.
- Type something like: You can also email us at hello@example.com and we will reply personally.
- Save.
Plain text only, up to 500 characters. It appears only on genuine failures.
How you find out
Three places, all administrator-only, and all appearing only when something has actually gone wrong:
- Settings → Recent send problems — the full picture, kept for 24 hours.
- A Dashboard widget — the three most recent problems.
- An admin notice — elsewhere in the admin area.
Troubleshooting checklist
| Problem | Try this |
|---|---|
| Nothing happens when I submit | Check the Form ID in the shortcode matches the form exactly. |
| “This form is not configured” | The Webhook URL is empty or was rejected. It must be a public address. |
| Visitors see an error but my test works | Look at Recent send problems. A test and a real submission take different routes. |
| A field is not arriving | Check its name is listed in the Fields box. Unlisted fields are dropped. |
| Nothing arrives from my platform | The Inbound shared secret is missing, or the header name is misspelled. It must be exactly X-Webhook-Engine-Secret. |
| The answer shows as a table when I wanted prose | Your field name is not one the plugin recognises, or set Response rendering to Markdown. |
| Callback answers never arrive | Confirm your workflow reads the return address from each message, then read the next section. |
| Everything worked, then stopped | Read the next section. |
Security software that can break the plugin
This section exists because it is genuinely hard to diagnose, and it is not a fault in the plugin.
Many hosts and security services put a bot check in front of your site — a page saying “Checking your browser before accessing” that runs briefly before letting you through. A real person’s browser passes it without noticing.
Your automation platform is not a browser. It cannot pass that check. If your host applies it to the address your platform is sending to, then:
- Information sent into your site never arrives.
- Callback answers never arrive.
- In the worst cases, ordinary form submissions fail now and then and visitors see “Something went wrong.”
How to tell if this is your problem
Everything looks correct, and your automation platform reports an error or a 403 when it tries to reach your site. Ask your host, or check your security plugin, and look at what happens to this address:
https://your-site.com/wp-json/
If a bot check or firewall rule stands in front of it, that is your answer.
How to fix it
Ask your host, or use your security plugin’s settings, to exempt this address from bot checks and firewall rules:
/wp-json/webhook-engine/
That is narrow enough to be safe. It exempts only this plugin’s own doors, which have their own passwords, and leaves the rest of your site protected.
Services that commonly do this: Cloudflare (Bot Fight Mode, WAF rules), Hostinger, SiteGround, WP Engine, Wordfence, Sucuri, All In One WP Security.
Tip
If you are testing and things behave inconsistently — working once, failing the next time — suspect this before suspecting the plugin.
Shortcode reference
| Option | Values | Notes |
|---|---|---|
id | a Form ID | Leave out to use the site-wide settings instead. |
response_render | auto, markdown, table, json | Only used when id is left out. |
| Option | Notes |
|---|---|
id | The Form ID this container belongs to. |
class | Extra CSS class names. |
Works with callback mode — see where the answer appears.
No data yet.
No data yet.
| Option | Values | Notes |
|---|---|---|
channel | any name | Which stream to show. Default default. |
mode | latest, list | One item, or a list. |
count | 1 to 20 | How many items a list shows. |
order | newest, oldest | Sort direction. |
offset | 0 to 49 | Skip this many first. |
field | a path | Show only part, such as field="stats.views". |
render | auto, markdown, table, json | How to display it. |
refresh | 0, or 5 and above | Seconds between automatic checks. 0 means never. |
archive | a web address | Where category and tag links point. |
meta | auto, none | none hides category and tag labels. |
Field names the plugin understands
Whenever your workflow sends something — an answer to a form, or information into your site — the plugin looks for these names. Capital letters, underscores, dashes and spaces are ignored.
| What it is | Names it accepts |
|---|---|
| The main text | body, markdown, content, text, answer, reply, message, output, article, description, summary |
| A heading | title, post_title, subject, heading, headline, name, label |
| Categories | categories, category, cats, sections, topics |
| Tags | tags, tag, keywords, terms, labels |
| An image | image_id (free), image_base64 (Pro), image / featured_image / image_url (Pro) |
| The stream name | channel — only when sending information into your site |
Wrappers removed automatically: data, payload, result, results, json, output, item, items, record, fields, attributes, object, and a list containing exactly one item. Up to four layers deep.
Nothing is required. If none of these names appear, your information is displayed as a labelled table instead of an article.
How your site is kept safe
- The incoming door is locked by default. It stays shut until you set a password of at least 16 characters.
- Your webhook address and any password attached to it never reach the visitor’s browser. Everything is sent from your server.
- Your site will not be tricked into contacting itself or your internal network. Addresses are checked when saved and again every time they are used.
- Failure messages give nothing away. A blocked address and an unreachable one produce exactly the same message, so nobody can use your form to map your network.
- Nothing sent to your site can run code on your page. Text is displayed as text; HTML in a message is shown as characters, not executed.
- Every image is verified by examining the file itself.
- Forms are rate-limited per visitor, and a hidden trap field quietly absorbs automated spam.
- Callback answers use two separate one-time passwords. One goes to your automation platform and can only deliver an answer. The other stays in the visitor’s browser and is the only thing that can read it. Knowing one never gives you the other, and both expire within minutes.
Reporting a security problem
If you believe you have found a vulnerability, please email support@deftmindlabs.com rather than posting it publicly, so it can be fixed before anyone can act on it. Reports are welcome, taken seriously, and acknowledged.
Frequently asked questions
| Question | Answer |
|---|---|
| Can I get a refund? | Billing is handled by Freemius as merchant of record, and their refund policy governs the transaction. The option chosen for these products is No refunds: because the plugin is a digital download, refunds are not generally offered. A full refund is given on request within 14 days only if the plugin was never downloaded. Requests after download are considered individually at our discretion, and must be made within 14 days of purchase. The paid 7-day trial exists precisely so you can evaluate the plugin in full before any charge is taken. |
| Do I need an AI subscription? | No. The plugin has no AI of its own. If your workflow uses AI, that is arranged on your platform. |
| Where are my API keys stored? | Not here. Any password you set for your webhook stays on your server and is never sent to a browser. |
| Can I have more than one form? | Yes. The free plugin allows one saved form; Pro raises that considerably. You can always use the site-wide settings without creating a named form. |
| Can two forms use different workflows? | Yes. Each form has its own address and settings. |
| Will this slow my site down? | No. Nothing happens until someone submits a form or your platform sends something. Callback is lighter than waiting, because your server is not held open. |
| Can visitors see my webhook address? | No. Submissions go to your own server first, which passes them on. |
| What if my workflow is down? | The visitor sees a polite failure message with their text preserved, and you get a record under Recent send problems. |
| Does the answer stay after a reload? | No. Use Draft post creation if you want it saved. |
Can I display a form answer with | No. That is only for information your platform sends in. Use |
| My workflow takes three minutes. Possible? | Yes — use Callback mode and set the deadline high enough. |
| Can I use callback with chat? | Not currently. Chat forms wait for the reply directly. |
| How do I test a callback without a real visitor? | Put the form on a draft page and preview it yourself. The Test webhook button carries no return address, so it cannot test the reply itself. |
| Is my visitors’ data stored? | Form submissions are passed to your workflow and not stored. Chat conversations are never stored. Only information sent into your site is stored, and only as much as your retention setting allows. |
Glossary
| Term | Meaning |
|---|---|
| Automation platform | The outside service where your logic runs — n8n, Make, Zapier and so on. |
| Callback | Answering later, by sending the answer to an address, instead of staying on the line. |
| Channel | A named stream of information sent into your site. |
| Deadline | How long a visitor waits for a callback answer. |
| Endpoint | A web address that accepts information. |
| Field | One box on a form. |
| JSON | A simple text format for exchanging information between computers. |
| Markdown | Simple formatting for text. |
| Payload | One package of information. |
| POST | The kind of web message used to send information somewhere. |
| Return URL | The one-time address your workflow sends a callback answer to. |
| Shortcode | Text in square brackets that WordPress turns into something real. |
| Webhook | A web address that accepts information sent by another computer. |
| Workflow | One piece of automation logic you have built. |