Webhooks: receiving and sending

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

Receive a webhook

Create a function with the HTTP / Webhook trigger. Its address is https://<your-project>.pgbhub.app/functions/<name>. Give that address to the service that sends you webhooks. Your function receives the body, query and headers, and can use db and env as usual. See Create and deploy a function.

Because anyone can reach that address, verify the sender:

• For a third-party service that signs its requests, keep its signing secret in Secrets & Env and verify the signature in your function before acting.
• PGB's own check uses an X-PGBHub-Signature header in the form t=<unix time>,v1=<hash>, where the hash covers <time>.<raw body>. A bad or missing signature returns 401, and a time more than five minutes off is refused to stop replays. A function whose trigger type is a webhook requires it.

Respond quickly with a success status, and do slow work in a job so the sender is not left waiting.

Send a webhook

Four places can call a URL for you:

From	How
Events & Webhooks	A rule with the Webhook (HTTP POST) target runs when a matching event fires. See Event rules
Cron Jobs	The HTTP target calls a URL on a schedule, with POST, GET, PUT or DELETE
Background tasks	A job with the webhook target retries automatically if it fails. See jobs
Actions	An Outbox Webhook URL, or a webhook effect, is called after the transaction commits

Target addresses must be public. Internal or private addresses are blocked.

Events you can subscribe to

Authentication emits user.created, user.login, user.login_failed, user.password_reset and session.revoked. Route them to a webhook with an event rule, for example to tell your CRM about every new user.

Test and debug

• Use Emit a Test Event on the Events page, then read Recent Event History for the status and number of attempts.
• Use Run on a cron job and open its Logs.
• Read a function's Execution Logs to see what arrived.

Good to know

• Deliveries can be repeated, so make receivers safe to run twice. Use an id from the payload to ignore duplicates.
• Do not put secrets in webhook URLs. Prefer a header or a signature.