Webhooks in both directions

What a webhook is

A webhook is an HTTPS request one system sends to another when something happens. Your project can receive them and send them.

Receive one

1. In Functions, choose + Create Function.
2. Name it payments_hook, pick a runtime and the HTTP / Webhook trigger.
3. Deploy it. Its address is https://<your-project>.pgbhub.app/functions/payments_hook.
4. Give that address to the service that will call you.

Your handler gets the body, query and headers, plus db and env.

Anyone can reach that address, so verify the sender. If the service signs its requests, put its signing secret in Secrets & Env and check the signature in your function before acting. PGB also checks an X-PGBHub-Signature header of the form t=<unix time>,v1=<hash> when present, where the hash covers <time>.<raw body>. Bad signatures get 401, and requests whose time is more than five minutes off are refused to stop replays.

Answer quickly with a success status. If the work is slow, enqueue a background job and return.

Send one

Several features can call a URL for you:

Feature	Setting
Events & Webhooks	A rule with the Webhook (HTTP POST) target
Cron Jobs	The HTTP target with POST, GET, PUT or DELETE
Tasks (jobs)	A job whose target is webhook, retried automatically
Actions	An Outbox Webhook URL or a webhook effect after the transaction commits

The destination must be a public address. Internal and private addresses are blocked.

Authentication events

Your project's authentication emits user.created, user.login, user.login_failed, user.password_reset and session.revoked. Create a rule under Events & Webhooks with the pattern user.created and a webhook target to tell another system about every new user.

Test and debug

• Choose Emit a Test Event and read Recent Event History. It shows the status (Success, Failed or Spend Cap) and attempts.
• Use Run on a cron job, then Logs.
• Open a function's Execution Logs to see exactly what arrived.

Make receivers safe

Deliveries can be repeated. Store an id from the payload and ignore ones you have already handled. Never put secrets in a webhook URL. Prefer a signature.

Try it

1. Deploy payments_hook that logs the body.
2. Add an event rule for user.created with that function as the target.
3. Create a user in Authentication, then read the function's logs and the event history.

Recap

• Receive webhooks in functions and verify the sender.
• Send them from event rules, cron jobs, jobs and actions.
• Expect repeats and design for them.