Skip to main content

Documentation Index

Fetch the complete documentation index at: https://paper.brimble.io/llms.txt

Use this file to discover all available pages before exploring further.

Brimble emits webhooks for deployment, project, domain, environment, DNS, autoscaling, subscription, and payment events. Wire them into your own endpoint, a Discord channel, or a Slack channel.

​
Prerequisites

  • A subscription on a plan that includes webhooks (Hacker and above).
  • An HTTPS endpoint to receive POSTs, or a Discord/Slack incoming-webhook URL.

​
How webhooks are configured

Webhooks are configured per subscription, not per project. Three URLs can be configured, independently:
URL fieldFormat expectedReceives
webhookUrlAn HTTPS endpoint you controlJSON POSTs (one event per request).
discordUrlA Discord channel webhook URL (https://discord.com/api/webhooks/.../...)Discord-formatted messages.
slackUrlA Slack incoming webhook URL (https://hooks.slack.com/services/...)Slack-formatted messages.
A single events list applies to all three destinations, whichever ones are set.

​
Set up a webhook

  1. Open the dashboard.
  2. Open your account settings, then Webhooks (or your team’s webhook settings, if you’re configuring a team subscription).
  3. Paste an endpoint URL into one or more of Webhook URL, Discord URL, or Slack URL.
  4. Pick the events you want to receive. Use Select all to subscribe to every event.
  5. Save.
Image needed: screenshot of the Webhooks settings page showing the three URL input fields (Webhook, Discord, Slack), the events checklist grouped by category (Deployment, Project, Domain, Environment, DNS, Autoscaling, Subscription, Payment), and a Save button
The next matching event delivers to every configured destination. Subscribe to specific events by listing them, or use ["*"] to subscribe to everything. Use [] to disable delivery without removing the URL.

​
What an HTTP webhook delivery looks like

POST /brimble HTTP/1.1
Host: your-endpoint.example.com
Content-Type: application/json

{
  "event": "deployment.success",
  "data": {
    "name": "main",
    "status": "ACTIVE",
    "user_id": "65a1...",
    "project_id": "65a2...",
    "team_id": null,
    "type": "web-service",
    "git": {
      "name": "acme-api",
      "full_name": "acme/acme-api",
      "id": 12345,
      "branch": "main",
      "installationId": 67890,
      "git": "github"
    },
    "compute": { "cpu": 1, "memory": 2, "storage": 0 },
    "message": "Add /healthz endpoint"
  }
}
Full payload schema for every event is in Webhook events reference.

​
Verifying the source

Webhooks reach your endpoint through Brimble’s webhook delivery layer. The body is JSON with {event, data}; nothing else changes between deliveries. Treat the endpoint URL itself as a shared secret. Don’t post your webhook URL publicly, in client-side code, in logs, or in screenshots. Anyone with the URL can post to it. For high-trust workflows (sending notifications you’ll act on, mutating state in response to webhook events), require an additional secret on top of the URL. The simplest pattern is appending a token to the path: 
https://your-endpoint.example.com/brimble?token=<long-random-string>
Reject any request that doesn’t include the matching token. The token is private to you and Brimble; only requests originating from your configured webhook will carry it.

​
Discord and Slack delivery

Discord and Slack URLs are pre-authenticated by URL secrecy. Each event is rendered as a channel message:
  • Discord gets an embed-style message with project name, event, and a short summary.
  • Slack gets a block-formatted message with the same fields.
You can configure all three URLs at once. The same event delivers to each independently. If your HTTP endpoint times out, the Discord and Slack messages still post.

​
Delivery semantics

  • At-least-once. A delivery may be retried if your endpoint fails or times out. Make your handler idempotent. Keying on data.project_id (or data.domain_id, etc.) plus event plus the relevant timestamp works for most resources.
  • Order is not guaranteed. Two events from the same project can arrive out of order. Use created_at / updated_at from data to reconcile.
  • Best-effort delivery. After repeated failures, a delivery is dropped. Your webhook stays enabled and continues to receive future events.
  • No automatic disable. If your endpoint has been broken for hours, deliveries are dropped, but new events keep being attempted.
Always return 200 quickly, then process asynchronously. Returning a non-2xx status, or taking too long to respond, triggers retries and surfaces as duplicate deliveries. Acknowledge first, queue the work, then run downstream calls outside the request handler.

​
Test a webhook

Click Send test event on the webhook in the dashboard. The dashboard fires a synthetic event of the type you pick at the URL you’ve configured. Test events use the same envelope as real events.

​
Troubleshooting

No deliveries at all. The webhook URL may not be saved. Check the webhook settings page in the dashboard. Also confirm the events list isn’t empty. Some events arrive, others don’t. The events you’re missing aren’t in your subscription list. Add them, or pass ["*"] to subscribe to everything. Discord/Slack worked once, now silent. The incoming-webhook URL was regenerated or removed at Discord/Slack (someone with admin on the channel did it, or the integration was reinstalled). Generate a new URL there and paste it back into Brimble’s webhook settings. Endpoint times out under load. Acknowledge fast (return 200 immediately), then process asynchronously. Don’t run downstream calls inside the request handler. Rapid duplicate deliveries. Most likely your endpoint returned a non-2xx status, triggering a retry. Confirm you return 200 even when the body is malformed; never error inside the handler before sending the response.

​
Next steps

Last modified on May 9, 2026