Admin · Allow about 15 minutes
Before you begin
Owner or Admin, integration access on your plan, and a developer-managed public HTTPS receiver. Beetl’s operator must have configured secret encryption and background delivery. This guide does not require sending a test to an external system until you choose to do so.
1. Create a scoped webhook connection
Open Settings → Integrations → Webhooks. Use Setup guide to review the delivery model, then choose New connection.
Enter a descriptive Connection name and a public HTTPS Destination URL on port 443. URL credentials, query parameters, fragments, and redirects are not supported.
Select only the knowledgebases and event types the receiving system needs, then choose Create webhook.
Store the signing secret securely in the receiver when Beetl displays it. It verifies webhook deliveries; it does not grant API or MCP access.
2. Test the receiver and verify delivery
Have your developer verify the webhook signature and timestamp against the raw request body, using the signing secret. Deduplicate by event ID and handle repeated or out-of-order delivery.
Use the connection’s test action only when the receiver is ready. Tests are queued for the background worker; queuing alone is not a successful delivery.
Inspect Delivery history and the latest attempts. Confirm success only after the receiver returns a successful response.
Notifications contain event and administrative record identifiers rather than article bodies, learner names, answers, or signature images. Use a separate scoped API key if the receiver needs permitted full records.
3. Maintain and troubleshoot the connection
Check configuration or plan messages when a connection is paused. Do not repeatedly recreate it to work around missing operator setup.
Use Pause when the receiver needs attention. Pausing stops new events and holds pending deliveries for up to seven days; dispatched requests cannot be recalled.
After repairing the receiver, resume delivery and retry eligible failures. Failed deliveries can be retried within seven days; history is retained for 30 days and shows the latest five attempts.
When replacing a signing secret, update the receiver securely. The replacement applies to subsequent attempts; check pending retries as well as new events.
Delete an obsolete connection only after checking dependent systems and reading the confirmation.
Check your result
The receiver accepts a verified test event and Delivery history records an actual successful response.
If something goes wrong
Webhooks unavailable: check plan access and ask the Beetl operator to verify encryption and background delivery configuration.
The test remains pending: check background-worker progress before diagnosing it as a receiver failure.
Signature verification fails: check the secret, exact raw body, timestamp, and event ID with your developer.
The receiver redirects or is unreachable: use a directly reachable public HTTPS endpoint on port 443 and inspect the recorded attempt.