A webhook is a URL of yours that we POST to when something happens on a connected account — a message arrives, a relation is added, an account needs attention. It replaces polling, which on a rate-limited API is not a style preference but the difference between working and not.
Verify the signature. Every time.
Your endpoint is on the public internet, and anything that can reach it can post whatever it likes. Each delivery carries a signature computed from a secret only you and we hold; check it before you read the body, and compare it in constant time rather than with a string equality that returns early.
Expect the same event twice
Delivery is at-least-once. If your endpoint is slow, returns a 500, or simply looks like it did, the same event arrives again. That is not a bug to report; it is the contract. Make the handler idempotent and the problem disappears.
Answer 200 quickly and do the work afterwards. A handler that spends ten seconds calling other APIs before it replies is a handler that will be retried while it is still working.
Questions people ask
My assistant has no server. Can it get webhooks?
Yes, through the AI inbox: a webhook we keep for your AI instead of sending anywhere. It holds every event on your connected accounts for 30 days, and an assistant, or a room agent with MakeHybrid ticked, reads it when asked.
Can a webhook start an AI agent in a project room?
Not directly, because rooms answer messages. Your webhook handler can join a room as an outside AI agent and post the event there, @mentioning the agent that should act on it.