Receive webhooks locally

Overview

Run a local server, expose it with a tunnel (e.g., ngrok), and point Blooio to the public URL.

Start a local server


const app = express();
app.use(express.json());

app.post("/webhooks/blooio", (req, res) => {
  console.log("[Blooio]", req.headers["x-blooio-event"], req.body);
  res.sendStatus(200);
});

app.listen(3001, () => console.log("Listening on http://localhost:3001"));

Expose the server

ngrok http http://localhost:3001

Copy the HTTPS URL from ngrok, e.g., https://abcd1234.ngrok.io.

Configure your webhook URL

Create a new webhook using the API:

curl -X POST 'https://api.blooio.com/v4/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://abcd1234.ngrok.io/webhooks/blooio"
  }'

Try it

The response is 201 with the subscription wrapped in a data envelope. It carries the signing_secret once, at creation:

{
  "data": {
    "id": "wh_abc123",
    "url": "https://abcd1234.ngrok.io/webhooks/blooio",
    "event_types": ["*"],
    "status": "active",
    "channel_id": null,
    "channel_type": null,
    "created_at": 1735324800000,
    "signing_secret": "whsec_a1b2c3d4e5f6789012345678901234567890abcdef"
  }
}

Note

The URL must be https://. A subscription receives every event type — switch on the type field in your handler to pick out the ones you care about.

Verify deliveries

You should see incoming events in your terminal. See event schemas in Webhook events.

Managing webhooks

List all webhooks

curl -X GET 'https://api.blooio.com/v4/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it

Update a webhook

Updatable fields are url and status (active or disabled):

curl -X PATCH 'https://api.blooio.com/v4/webhooks/{webhookId}' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "disabled"
  }'

Try it

Delete a webhook

curl -X DELETE 'https://api.blooio.com/v4/webhooks/{webhookId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it

Rotate webhook secret

If you need a new signing secret:

curl -X POST 'https://api.blooio.com/v4/webhooks/{webhookId}/secret/rotate' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it

Inspect deliveries

curl -X GET 'https://api.blooio.com/v4/webhooks/{webhookId}/deliveries' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it