Inbound hooks

An inbound hook gives another service an address to call. When it does, Pawabase checks the request is genuine, then starts a flow or emits an event that your subscriptions react to. Use one when something outside Pawabase should make something happen inside it: a payment succeeded, a pull request opened, an order shipped, a form was submitted.

Create one

Open Webhooks → Inbound hooks → New inbound hook

Fill in the fields below.

Save and copy the address

It looks like https://<your-api>/hooks/v1/<environment>/<slug>. It needs no API key: the signature is the credential.

Give the address and secret to the other service

Paste them where that service asks for a webhook URL and signing secret.

Field	Meaning
Name and Description	For your team
Slug	The last part of the address. Lowercase letters, digits and dashes, 2 to 63 characters, starting with a letter or digit.
Verification	How requests are checked. See below. Default HMAC SHA-256.
Signature header	The header that carries the signature. Default `x-signature`.
Secret	The shared secret, at least 16 characters. Store it as a secret and write `secret://NAME`.
Then	Run a flow, or emit an event (the default).
Enabled	Pause without deleting. A disabled or unknown hook answers `404`.

Verification methods

Method	What is checked	Typical sender
HMAC SHA-256	The header holds the hex HMAC-SHA256 of the raw body, keyed with your secret	GitHub (`x-hub-signature-256`, with its `sha256=` prefix) and most services
HMAC SHA-512	The same with SHA-512	Services that sign with SHA-512
HMAC SHA-256 with timestamp	The signature covers a timestamp and the body. The timestamp is read from a header named like the signature header, with `signature` replaced by `timestamp` (for example `x-example-signature` and `x-example-timestamp`).	Services that sign a timestamp to stop replays
Pawabase signature	The `t=<time>,v1=<signature>` format, signed over `<time>.<body>`, with a tolerance of five minutes	Stripe, and another Pawabase project
Shared token	The header equals your secret exactly	Services that send a fixed token
None	Nothing	Avoid. Anyone with the address can start your flow.

Match Verification and Signature header to what the sender does, and check the sender’s own documentation. If the signature is missing or wrong, the request is refused with 401 and nothing runs.

Choose None only for testing. A hook without verification lets anyone who learns the address trigger your flow or event.

What your flow receives

The flow’s input is an envelope, not just the body:

{
  "hook": "github-issues",
  "headers": { "x-github-event": "issues", "content-type": "application/json", "user-agent": "GitHub-Hookshot/…" },
  "body": { "action": "opened", "issue": { "title": "Login fails on Safari" } }
}

Field	Meaning
`hook`	The hook’s slug
`headers`	The request’s `x-…` headers, `user-agent` and `content-type` (the signature header is removed)
`body`	The request’s JSON body. If it isn’t valid JSON, `{ "raw": "<the text>" }`

So in the flow you read {{ input.body.action }} and {{ input.body.issue.title }}, and the sender’s event name from {{ input.headers['x-github-event'] }}. When Then is Event, the same envelope is the event’s payload, and subscriptions can react to it.

What the sender gets back

Status	Meaning
202	Accepted. A flow was queued (`job_id` in the answer) or an event was emitted (`event_id`). The work runs in the background.
401	The signature was missing or didn’t match.
404	No such hook, or it is disabled.
413	The body is larger than 1 MB.

Because the sender is answered immediately, your flow can take as long as it needs. Failures are visible under Activity → Jobs.

Example: a GitHub issue starts a flow

Create a hook github-issues, Verification HMAC SHA-256, Signature header x-hub-signature-256, secret from secret://GITHUB_WEBHOOK_SECRET, Then a flow triage-issue.
In GitHub: Settings → Webhooks → Add webhook, paste the address, content type application/json, and the same secret.
In triage-issue, use {{ input.body.issue.title }} to create a record, post to a channel or ask a model to classify it.

Example: Stripe payment emits an event

Create a hook stripe, Verification Pawabase signature, Signature header stripe-signature, secret from secret://STRIPE_WEBHOOK_SECRET, Then an event stripe.received. Stripe signs <timestamp>.<body> and sends t=…,v1=…, which is the same format Pawabase checks.
Subscribe a flow to stripe.received and branch on {{ input.body.type }}.

Manage it from code

import { manage } from "@pawabase/client/manage";

const m = manage(pawabase);
await m.inboundHooks.create({
  slug: "github-issues",
  name: "GitHub issues",
  verification: "hmac-sha256",
  signature_header: "x-hub-signature-256",
  target_type: "flow",
  target: "triage-issue",
  secret: "secret://GITHUB_WEBHOOK_SECRET",
});

pb.manage.inbound_hooks.create({
    "slug": "github-issues",
    "name": "GitHub issues",
    "verification": "hmac-sha256",
    "signature_header": "x-hub-signature-256",
    "target_type": "flow",
    "target": "triage-issue",
    "secret": "secret://GITHUB_WEBHOOK_SECRET",
})

Test it

Send a request yourself while the hook is set to a known secret:

BODY='{"action":"opened","issue":{"title":"Test"}}'
SIG=$(printf %s "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST "$URL/hooks/v1/production/github-issues" \
  -H "content-type: application/json" -H "x-hub-signature-256: $SIG" -d "$BODY"

Then open Activity → Flow runs to see the run and what it received. Each hook also shows how many requests it has received and when the last one arrived.

Troubleshooting

Problem	Check
`401`	The secret differs from the sender’s, Verification doesn’t match the sender’s method, the signature header name is wrong, or you signed something other than the raw body.
`404`	The slug or environment in the address is wrong, or the hook is disabled.
The flow can’t find the field	Read from `input.body…`, not `input…`.
Nothing happens after `202`	Open Activity → Jobs and Flow runs for the failure.
The sender times out	Pawabase answers immediately. Check the sender can reach your API address.

Getting started

Events

Webhooks

Operate

Create one

Verification methods

What your flow receives

What the sender gets back

Example: a GitHub issue starts a flow

Example: Stripe payment emits an event

Manage it from code

Test it

Troubleshooting

​Create one

​Verification methods

​What your flow receives

​What the sender gets back

​Example: a GitHub issue starts a flow

​Example: Stripe payment emits an event

​Manage it from code

​Test it

​Troubleshooting

Create one

Verification methods

What your flow receives

What the sender gets back

Example: a GitHub issue starts a flow

Example: Stripe payment emits an event

Manage it from code

Test it

Troubleshooting