Webhooks

> Let external services push data to your Brickr routes in real time.

A webhook is an HTTP callback -- an external service sends a request to a URL you provide, and Brickr executes a flow in response. Webhooks are how you receive real-time events from payment providers, messaging platforms, version control systems, and other services.

How webhooks work

1. You create a route in Brickr with a webhook trigger. 2. Brickr provides a unique webhook URL for that route. 3. You register this URL with the external service. 4. When an event occurs, the external service sends an HTTP request to your webhook URL. 5. Brickr receives the request and executes your flow, passing the incoming data to the Start Node.

Setting up a webhook

1. Create a route

Create a new route in any api. Use the POST method, since most webhook providers send POST requests.

POST /webhooks/stripe
POST /webhooks/github

2. Configure the webhook trigger

Open the route in the Builder and configure the Start Node with a Webhook trigger. This generates a unique webhook URL.

3. Register the URL

Copy the webhook URL and paste it into the external service's webhook configuration. Each service has its own settings page for this.

4. Build your flow

Design the flow to process the incoming webhook data:

1. Get JSON Body -- Extract the payload from the incoming request. 2. Get Property -- Pull out specific fields. 3. Branch -- Route logic based on event type. 4. DB Insert / Send Email / Return JSON -- Take action based on the event.

Webhook URLs are public endpoints. Consider adding verification logic to confirm requests are authentic. Many services include a signature header you can validate.

Webhook data

The external service sends data in the request body, typically as JSON. The exact structure depends on the service and event type.

Common patterns:

| Service | Event Example | Payload Contains | |---------|--------------|-----------------| | Stripe | payment_intent.succeeded | Payment amount, customer ID | | GitHub | push | Commits, branch, repository | | Slack | message | Message text, channel, user |

Responding to webhooks

Most webhook providers expect a quick response (usually a 200 status code) to confirm receipt. Use the Return JSON node at the end of your flow to send a response.

{
  "received": true
}

If your webhook route does not respond within the timeout period, the external service may retry the request. Design your flow to handle duplicate deliveries gracefully.

Security

To verify that webhook requests are genuine:

1. Check for a signature header (e.g., X-Hub-Signature for GitHub, Stripe-Signature for Stripe). 2. Use the Get Header node to read the signature. 3. Use the Hash node to compute the expected signature using your shared secret. 4. Compare the two signatures and reject the request if they do not match.

Always validate webhook signatures in production. Without validation, anyone who discovers your webhook URL could send fake events.

What's next?

| Topic | Description | |-------|-------------| | Email | Send emails from your flows | | Cron Jobs | Schedule flows to run on a timer | | Form Triggers | Trigger flows from form submissions |