> For the complete documentation index, see [llms.txt](https://playbook.nativemsg.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://playbook.nativemsg.com/mcp/tool-reference/webhooks.md).

# Webhooks

Webhooks push account events to your own systems — the inbound counterpart to the `request` action inside an experience. nativeMsg POSTs each event to your URL; the receiver must answer **200 within 5 seconds** or delivery is retried.

**Event types:** `inbound` (contact replies), `outbound` (messages sent), `message_status` (delivery updates).

| Tool             | What it does                                                                                                                                                                              | Key inputs           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `list_webhooks`  | Registered webhook receivers                                                                                                                                                              | paging               |
| `get_webhook`    | One webhook: url and event subscriptions                                                                                                                                                  | `webhook_id`         |
| `create_webhook` | Register a receiver URL for chosen event types. Returns the webhook including `secretKey`, which nativeMsg sends in the `x-api-key` header of every delivery — verify it on your receiver | `url`, `events`      |
| `update_webhook` | Change the URL or event list (`events` replaces the whole list). Deliveries move to the new URL at once                                                                                   | `webhook_id`, fields |
| `delete_webhook` | Stop deliveries to that URL. Cannot be undone                                                                                                                                             | `webhook_id`         |

## Notes

* **Verify `x-api-key`:** reject deliveries whose header doesn't match the `secretKey` returned at creation.
* Webhook changes silently affect downstream systems — AI clients treat update/delete as confirm-first actions.
* Use webhooks when your system needs to know what happened in messaging; use an experience's `request` action when the conversation needs data from your system.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://playbook.nativemsg.com/mcp/tool-reference/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.