Webhooks
Receive a signed POST when a record finishes or a pushed document is ready, and read the delivery log.
A webhook is a web address of yours that Baseera calls when something happens. Baseera has two kinds, and both are signed so your server can check a call really came from Baseera.
| Webhook | Set up on | Events |
|---|---|---|
| Finish webhook | The agent's Immersive mode page | A record is finished in immersive mode. Also eval.run.finished for test runs started from your CI or by a tool manifest change. |
| Knowledge webhook | A knowledge base page, Webhook | A document is ready and A document failed, for documents pushed through the API. |
Only Owners and Admins can change a webhook. If your organization requires two-factor, you must have entered your code in this session first.
Set up the finish webhook
Open the agent and choose Immersive mode. Find Finish webhook.
Enter the Address (https), for example https://example.com/webhooks/baseera-finish.
Press Save webhook. Baseera checks that the address is public before it saves.
Copy the Signing secret now. It is shown once and starts with whsec_. Press I've stored it when it is safe in your server's secrets.
To change the address or get a new secret, press Change address or secret and save again. Saving again rotates the secret and destroys the old one. Remove webhook stops deliveries, and deliveries still waiting are dropped.
The knowledge webhook works the same way on the knowledge base page, with Events checkboxes.
What a call contains
For a finished record, Baseera sends the record's trail as a signed POST: flags, fixes, approvals, overrides and the finish. Draft values and signal data are left out when the agent is set not to store tool data. A payload can be up to about 250 KB, so your receiver must accept that.
A knowledge call carries ids and a status, never document text.
Verify each call with verifyWebhook from @baseera/node. It checks the Baseera-Signature header, which has a timestamp and a signature, with a constant-time comparison. Details are in the Webhooks API reference.
Delivery and retries
- Finish events: Baseera tries each delivery twice, a retry after the first failure, and then shows it as Failed. A call must be answered with a 2xx status within 5 seconds.
- Knowledge events: Baseera tries up to six times, spread over roughly 50 minutes, then shows Gave up. The timeout is 10 seconds.
- A retry waits for the next worker run, about a minute.
- Finishing a record never waits on your server. If your receiver is down, the finish still works.
- Redirects are not followed, and the address must be public
https. Private, local and internal addresses are refused every time Baseera sends.
There is no manual resend and no automatic disabling of a dead endpoint yet.
Read the delivery log
Recent deliveries lists each delivery with Status (Waiting, Delivered, Failed or Gave up), Tries, When and the reason a delivery failed:
| Reason | Meaning |
|---|---|
| Address not allowed | The address is not public https, or uses a blocked port. |
| Address not found | The host name did not resolve. |
| Timed out | Your server did not answer in time. |
| Couldn't connect | The connection failed. |
| Redirected (not followed) | Your address redirected. Use the final address. |
| Answer N | Your server answered with this status. A 2xx counts as delivered. |
If the latest finish delivery failed, the agent's Overview shows Finish webhook problem with "Last delivery failed" or "N deliveries failed this week", the last reason and Open the webhook settings.
What can go wrong
| Message | Cause and fix |
|---|---|
| "Enter an https address, for example https://example.com/webhook." | Use https. |
| "That address can't be used. It must be public: not a private, local or internal address." | Use a public address. For local work, expose it through a tunnel. |
| "We couldn't find that address. Check the host name." | Fix the host name. |
| "Couldn't check the address right now, so it wasn't saved." | Try again in a moment. |
| "Only owners and admins can change the webhook." | Ask an owner or admin. |
| "Enter your two-factor code before changing the webhook. Open Security to continue." | Sign in with your code first. |
| Signature check fails in your code | Use the raw request body, the current secret and verifyWebhook. After you rotate, the old secret stops working. |