Inbound Webhooks, Signatures and Replays
One authenticated endpoint that turns an event from anywhere into something that happens here. How the token and the HMAC signature work, why replay protection matters more than people expect, and the honest limit on what an inbound event can do.
The usual way vendors handle "connect to our system" is a per-vendor list: a Shopify integration, a WooCommerce integration, a Zoho integration, each maintained separately and each slightly behind. The alternative is one authenticated door that anything can knock on. It is less impressive on a logo wall and it covers vastly more ground, because the list of systems that can make an HTTP request is longer than any integrations page.
That is the design here: a single inbound webhook, authenticated by a per-organisation token, optionally verified by an HMAC signature, protected against replays, and able to either raise a notification or trigger one of your own workflow rules.
What it looks like on the wire
The request
Element What it is for
A POST to the inbound webhook endpoint One URL for every source. There is no per-vendor path
An inbound token header Identifies your organisation and authorises the call
A signature header — HMAC-SHA256 of the body Proves the body was not altered, if a secret is set
A title and a message What the notification says when it arrives
An optional URL Where the notification links to. Usually the record in the other system
An optional event name plus a data object Triggers any workflow rules you have matched to that event
The last row is the interesting one and the reason this endpoint is more than a message printer. An event name lets you build the response on your side — route it, escalate it, notify a role, chain further actions — without the sending system knowing anything about how you have configured your organisation.
The signature, and when it is compulsory
The token authorises; the signature authenticates the body. They answer different questions and confusing them is the usual mistake.
A token proves the caller possesses a shared secret. It does nothing about whether the body arrived intact or whether the caller is who they claim — anyone who has ever seen your token in a log, a screenshot, a support ticket or a browser network tab can send anything. An HMAC signature over the body, computed with a secret you never transmit, means the payload can be verified without trusting the transport.
If a secret is set, the signature is required
Not optional, not best-effort. A credential with a secret configured rejects an unsigned request and an incorrectly signed one, and the two produce different messages so you can tell which mistake you made during setup. If no secret is set, the token alone is accepted — which is a legitimate choice for a low-stakes internal script and the wrong choice for anything touching money.
Replay protection, which sounds academic and is not
A replay is the same valid request sent twice. It happens far more often through ordinary failure than through attack: a sender times out waiting for a response and retries, a queue redelivers, someone re-runs a script to check it worked. Without protection, one payment notification becomes three.
The endpoint records what it has already processed and returns the original response to a repeat, flagged so the caller can tell it was recognised as a replay rather than processed again. That means a well-behaved sender that retries on timeout is safe by default, which is the property you actually want — because a sender that never retries loses events, and one that retries without idempotency duplicates them.
Why the flag matters, concretely
This is the whole argument for idempotency at the receiving end rather than discipline at the sending end: you do not control the sender, and every reliable sender retries.
What to point at it
-
Your own website or booking form
A submitted enquiry, order or booking becomes a notification that lands where your team looks, without anybody polling a mailbox. The most common and most immediately useful case.
-
A no-code automation platform
Zapier or Make sits between hundreds of applications and this endpoint. If the other end of your integration has a trigger in one of those, you have an integration and you have not written code.
-
A payment or messaging provider's own callback
Anything that can be configured to call a URL on an event. Set a secret for these — they are exactly the case where a token alone is not enough.
-
A script on your own machine
The pragmatic case. A cron job that reads something nobody has an integration for and posts a summary here once a day is often a better answer than a project.
-
Another instance of your own systems
A stock feed, a machine, a sensor gateway. If it speaks HTTP, it can reach this.
The limits, precisely
What AWRA OpsHub does today
- One endpoint for every source, authorised by a per-organisation token with a scope.
- Optional HMAC-SHA256 body signing, enforced rather than advisory when a secret is set.
- Replay detection that returns the original response and marks it as a replay.
- An optional event name that triggers your matching workflow rules, queued so the caller is never held waiting while workflows and their outbound actions run.
- The resulting notification fans out to whatever channels you have connected — chat, email, SMS, WhatsApp.
More we can add to your workspace
- An inbound event that creates business records — a sales order, an invoice, a stock movement or a customer. Today it notifies, and it can trigger a workflow.
- Payload mapping and transformation — a screen where you tell it that the other system's "qty" is your "quantity".
- Per-source endpoints and vendor-specific parsers, so a provider's native payload shape has to be reshaped by whatever sits in front — which is usually where Zapier or Make earns its place.
- An inbound event log you can browse as a debugging console, beyond the replay records.
The first bullet is the one to plan around. If your requirement is "orders from my website should become sales orders here", the inbound webhook is not that — the API is, and the two are often confused because both are described as integration.
Anything above that you need, we can build for you
Everything listed above as something we can add describes what ships in the standard product today — it is a starting point, not a limit on what AWRA OpsHub can do for your organisation. Kenya's eTIMS integration and its maintained payroll engine are both in the product because clients needed them and commissioned them; neither appeared by itself, and the same door is open for whatever you just read about. One qualification so this is worth what it claims: a small number of things on this blog we deliberately leave to a specialist rather than build — a statutory ledger we will not sign our name to, a rule that would decide a tax question for you, a clinical or member-funds record that belongs in a regulated system — and where that is true the post says so in those words. Everything else is a scope, a timeline and a price.
The operational work, which is what most commissions actually are
An extra approval stage in a chain that does not match the standard one, a custom field set on employees or assets that only your sector needs, an expiry that has to block an order rather than send an email, a report your board asks for in a shape nothing produces, or a scanner or weighbridge feeding the goods-in door. These are the commissions we are asked for most often and the smallest ones we quote — and unlike a revenue-authority pipeline, none of them waits on a regulator.
The module-shaped additions, which are the ones readers ask for most often
A price list with real discount authority, a customer-facing quotation that expires, a bill of materials or recipe costing, a staff advance that is issued, acquitted and chased, a member or unit ledger, a matching rule that holds a payment. Each of these is a build rather than a setting, and each has been quoted before — a bigger piece of work than a custom field, with a written spec and a date instead of a roadmap slide.
The report, document or pack nothing currently produces
The board pack in the shape your board actually asks for, a donor or funder layout, an invoice or receipt template carrying what your regulator or your customer expects, a dataset the report builder cannot reach yet. Usually the fastest thing on this list to deliver, because the data is already in the system.
Systems, rails and hardware you already run
The accounting package, CRM, online store, core banking or custom database you intend to keep — connected through our API so a fact is entered once and appears everywhere it is needed. Plus the physical edge: a scanner, a scale, a weighbridge or a till peripheral feeding the door it belongs to.
How it works: you describe the requirement, we return a written scope, timeline and cost, and once agreed it is built into your environment and maintained as part of the product. Nothing here waits on a regulator or a published specification, which is why operational builds are the ones we quote fastest. Tell us the requirement that would otherwise rule us out — that is a better first conversation than a demo.
Tell us what your operation needsSetting it up without a bad afternoon
In this order
- Generate the credential and copy the token. Set a secret if anything financial or customer-facing will use it.
- Send one request with a title and message only. Confirm the notification arrives before adding anything else.
- If you set a secret, get the signature working next, on its own, before adding an event name. Two new things at once means you cannot tell which is broken.
- Add the event name and the data object last, and check the workflow fired rather than assuming it did.
- Then deliberately send the same request twice and confirm you get one notification and a replay marker. This is a thirty-second test and it is the one that tells you your integration is safe to retry.
Our take
One signed, replay-protected door beats a list of vendor integrations that are each slightly out of date. Set a secret for anything that matters, get the signature working before you add an event name, and test the duplicate deliberately. But be clear on the boundary: this notifies and triggers workflows — it does not create business records, and if that is what you need, you want the API.
One door, signed and replay-safe
A per-organisation token, optional HMAC body signing that is enforced rather than advisory, replay detection that makes retries safe, and an event name that fires your own workflow rules.
See plans & pricingFrequently asked questions
What is the inbound webhook for?
Turning an event that happens somewhere else into something that happens here: a notification that reaches your connected channels, and optionally a trigger for one of your own workflow rules. One authenticated endpoint serves every source, rather than a per-vendor list that is always slightly behind.
How is an inbound request authenticated?
A per-organisation inbound token header authorises the call, and an HMAC-SHA256 signature over the request body authenticates the payload. They answer different questions: the token proves possession of a shared secret, the signature proves the body was not altered. If a secret is configured on the credential, the signature is required and an unsigned request is rejected.
What happens if the same event is delivered twice?
It is recognised as a replay: the original response is returned with a marker saying so, and nothing is created a second time. This matters more than it sounds, because duplicates arrive through ordinary failure — a sender times out and retries, a queue redelivers, someone re-runs a script. Making retries safe is what lets senders retry at all.
Can an inbound webhook create records such as sales orders?
No. It raises a notification and can trigger a workflow; it does not create a sales order, an invoice, a stock movement or a customer. If your requirement is "website orders should become sales orders", that is the API rather than this endpoint — a common and expensive confusion, because both get described as integration.
Can it reshape a provider's payload?
No. There is no mapping or transformation screen, so a provider's native payload shape has to be reshaped by whatever sits in front of the endpoint. This is where a no-code platform such as Zapier or Make genuinely earns its place: it speaks both shapes and needs no code from you.
How should we test the setup?
One thing at a time. Send a title and message only and confirm the notification arrives. Then get the signature working alone. Then add the event name and check the workflow actually fired. Finally send the identical request twice on purpose and confirm you get one notification and a replay marker — a thirty-second test that tells you the integration is safe to retry.
