> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/webhooks.md). # Webhooks These API endpoints allow you to manage Webhooks. To learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter ## GET /api/v1/webhooks/waba/ > Webhook sent by WhatsApp Business API to your endpoint(s)\ > \ > Only admin Users can see a list of all Users WABA Webhooks.\ > Other Users receive a list of one element of their own WABA Webhook (if configured).\ > \ > This resource describes configuration of webhook sent from WhatsApp Business API / WhatsApp to one of your apps\ > (or systems). WhatsApp Business API itself allows you to integrate only one webhook. With our API you can set up\ > multiple per-user webhooks.\ > \ > See Integration chapter to learn more about per-user webhooks. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Webhooks","description":"These API endpoints allow you to manage Webhooks.\n\nTo learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter"}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"PaginatedWabaWebhookList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/WabaWebhook"}}}},"WabaWebhook":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"user":{"allOf":[{"$ref":"#/components/schemas/ShortUser"}],"readOnly":true},"url":{"type":"string","format":"uri","description":"Remember to use `https://` URLs for your webhooks!\n\n**Note**: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}."},"on_incoming_message":{"type":"boolean","description":"Call this Webhook on every new Message coming from WhatsApp to Inbox.
This is how WhatsApp webhooks are called."},"on_outgoing_message":{"type":"boolean","description":"Call this Webhook on every new Message sent from Inbox to WhatsApp.
You should use this setting when integrating a system in which you want to have complete copies of all your conversations."},"on_assigned":{"type":"boolean","description":"Call this Webhook when existing Chat is assigned to this User or a new Message is posted to the Chat already assigned to this User.

You should set this when integrating a bot with this Webhook.
This is similar to how human Users are notified by desktop notifications. "},"on_message_echo":{"type":"boolean","description":"Call this Webhook when a message is sent from your WhatsApp Business number via the 360dialog messaging API, outside the Inbox.
The webhook receives the original Cloud API \"message_echoes\" payload, so your integration can keep a complete copy of the conversation. Messages sent through the Inbox API are not echoed here - use \"on outgoing message\" for those."},"headers":{"description":"Additional headers needed when calling a Webhook. Each header needs to be provided as a key-value pair in JSON format.
Useful for things like API keys with Authorization or other headers.

Example: {\"Authorization\": \"Token 1234567890qwertyuiop\"}"}},"required":["id","url","user"]},"ShortUser":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"username":{"type":"string","description":"Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.","pattern":"^[\\w.@+-]+$","maxLength":150},"url":{"type":"string","format":"uri","readOnly":true}},"required":["id","url","username"]}}},"paths":{"/api/v1/webhooks/waba/":{"get":{"operationId":"listWabaWebhooks","description":"Webhook sent by WhatsApp Business API to your endpoint(s)\n\nOnly admin Users can see a list of all Users WABA Webhooks.\nOther Users receive a list of one element of their own WABA Webhook (if configured).\n\nThis resource describes configuration of webhook sent from WhatsApp Business API / WhatsApp to one of your apps\n(or systems). WhatsApp Business API itself allows you to integrate only one webhook. With our API you can set up\nmultiple per-user webhooks.\n\nSee Integration chapter to learn more about per-user webhooks.","parameters":[{"name":"limit","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"name":"offset","required":false,"in":"query","description":"The initial index from which to return the results.","schema":{"type":"integer"}}],"tags":["Webhooks"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedWabaWebhookList"}}},"description":""}}}}}} ``` ## POST /api/v1/webhooks/waba/ > One user can have multiple WABA Webhook configs, for example:\ > \ > \`\`\`json\ > \[{\ > "id": 1,\ > "user": {"id": 23, "username": "string", "url": "string"},\ > "url": " > "on\_incoming\_message": true,\ > "on\_outgoing\_message": false,\ > "on\_assigned": false\ > }, {\ > "id": 2,\ > "user": {"id": 23, "username": "string", "url": "string"},\ > "url": " > "on\_incoming\_message": false,\ > "on\_outgoing\_message": true,\ > "on\_assigned": false,\ > "headers": {}\ > }, {\ > "id": 3,\ > "user": {"id": 23, "username": "string", "url": "string"},\ > "url": " > "on\_incoming\_message": false,\ > "on\_outgoing\_message": false,\ > "on\_assigned": true,\ > "headers": {"Authorization": "Token 8aeb44f5a318542d32bb13019d68198467ee21f0"}\ > }]\ > \`\`\`\ > \ > or you can have following webhooks:\ > \ > \`\`\`json\ > \[{\ > "id": 1,\ > "user": {"id": 23, "username": "string", "url": "string"},\ > "url": " > "on\_incoming\_message": true,\ > "on\_outgoing\_message": true,\ > "on\_assigned": false\ > }, {\ > "id": 2,\ > "user": {"id": 23, "username": "string", "url": "string"},\ > "url": " > "on\_incoming\_message": false,\ > "on\_outgoing\_message": false,\ > "on\_assigned": true,\ > "headers": {"Authorization": "Token 8aeb44f5a318542d32bb13019d68198467ee21f0"}\ > }]\ > \`\`\`\ > \ > After this webhook is created, WABA webhooks are propagated to your URL starting from next webhook.\ > \ > See WABA Webhook section to learn more how propagation works. ````json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Webhooks","description":"These API endpoints allow you to manage Webhooks.\n\nTo learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter"}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"WabaWebhook":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"user":{"allOf":[{"$ref":"#/components/schemas/ShortUser"}],"readOnly":true},"url":{"type":"string","format":"uri","description":"Remember to use `https://` URLs for your webhooks!\n\n**Note**: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}."},"on_incoming_message":{"type":"boolean","description":"Call this Webhook on every new Message coming from WhatsApp to Inbox.
This is how WhatsApp webhooks are called."},"on_outgoing_message":{"type":"boolean","description":"Call this Webhook on every new Message sent from Inbox to WhatsApp.
You should use this setting when integrating a system in which you want to have complete copies of all your conversations."},"on_assigned":{"type":"boolean","description":"Call this Webhook when existing Chat is assigned to this User or a new Message is posted to the Chat already assigned to this User.

You should set this when integrating a bot with this Webhook.
This is similar to how human Users are notified by desktop notifications. "},"on_message_echo":{"type":"boolean","description":"Call this Webhook when a message is sent from your WhatsApp Business number via the 360dialog messaging API, outside the Inbox.
The webhook receives the original Cloud API \"message_echoes\" payload, so your integration can keep a complete copy of the conversation. Messages sent through the Inbox API are not echoed here - use \"on outgoing message\" for those."},"headers":{"description":"Additional headers needed when calling a Webhook. Each header needs to be provided as a key-value pair in JSON format.
Useful for things like API keys with Authorization or other headers.

Example: {\"Authorization\": \"Token 1234567890qwertyuiop\"}"}},"required":["id","url","user"]},"ShortUser":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"username":{"type":"string","description":"Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.","pattern":"^[\\w.@+-]+$","maxLength":150},"url":{"type":"string","format":"uri","readOnly":true}},"required":["id","url","username"]}}},"paths":{"/api/v1/webhooks/waba/":{"post":{"operationId":"createWabaWebhook","description":"One user can have multiple WABA Webhook configs, for example:\n\n```json\n[{\n \"id\": 1,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": true,\n \"on_outgoing_message\": false,\n \"on_assigned\": false\n}, {\n \"id\": 2,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": false,\n \"on_outgoing_message\": true,\n \"on_assigned\": false,\n \"headers\": {}\n}, {\n \"id\": 3,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": false,\n \"on_outgoing_message\": false,\n \"on_assigned\": true,\n \"headers\": {\"Authorization\": \"Token 8aeb44f5a318542d32bb13019d68198467ee21f0\"}\n}]\n```\n\nor you can have following webhooks:\n\n```json\n[{\n \"id\": 1,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": true,\n \"on_outgoing_message\": true,\n \"on_assigned\": false\n}, {\n \"id\": 2,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": false,\n \"on_outgoing_message\": false,\n \"on_assigned\": true,\n \"headers\": {\"Authorization\": \"Token 8aeb44f5a318542d32bb13019d68198467ee21f0\"}\n}]\n```\n\nAfter this webhook is created, WABA webhooks are propagated to your URL starting from next webhook.\n\nSee WABA Webhook section to learn more how propagation works.","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}}},"description":""}}}}}} ```` ## GET /api/v1/webhooks/waba/{id}/ > Create WABA Webhook for this user (currently logged in user) ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Webhooks","description":"These API endpoints allow you to manage Webhooks.\n\nTo learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter"}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"WabaWebhook":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"user":{"allOf":[{"$ref":"#/components/schemas/ShortUser"}],"readOnly":true},"url":{"type":"string","format":"uri","description":"Remember to use `https://` URLs for your webhooks!\n\n**Note**: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}."},"on_incoming_message":{"type":"boolean","description":"Call this Webhook on every new Message coming from WhatsApp to Inbox.
This is how WhatsApp webhooks are called."},"on_outgoing_message":{"type":"boolean","description":"Call this Webhook on every new Message sent from Inbox to WhatsApp.
You should use this setting when integrating a system in which you want to have complete copies of all your conversations."},"on_assigned":{"type":"boolean","description":"Call this Webhook when existing Chat is assigned to this User or a new Message is posted to the Chat already assigned to this User.

You should set this when integrating a bot with this Webhook.
This is similar to how human Users are notified by desktop notifications. "},"on_message_echo":{"type":"boolean","description":"Call this Webhook when a message is sent from your WhatsApp Business number via the 360dialog messaging API, outside the Inbox.
The webhook receives the original Cloud API \"message_echoes\" payload, so your integration can keep a complete copy of the conversation. Messages sent through the Inbox API are not echoed here - use \"on outgoing message\" for those."},"headers":{"description":"Additional headers needed when calling a Webhook. Each header needs to be provided as a key-value pair in JSON format.
Useful for things like API keys with Authorization or other headers.

Example: {\"Authorization\": \"Token 1234567890qwertyuiop\"}"}},"required":["id","url","user"]},"ShortUser":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"username":{"type":"string","description":"Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.","pattern":"^[\\w.@+-]+$","maxLength":150},"url":{"type":"string","format":"uri","readOnly":true}},"required":["id","url","username"]}}},"paths":{"/api/v1/webhooks/waba/{id}/":{"get":{"operationId":"retrieveWabaWebhook","description":"Create WABA Webhook for this user (currently logged in user)","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"description":"A unique integer value identifying this WABA webhook.","required":true}],"tags":["Webhooks"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}}},"description":""}}}}}} ``` ## PUT /api/v1/webhooks/waba/{id}/ > Update a WhatsApp webhook: its URL, the events it is called for, and its headers. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Webhooks","description":"These API endpoints allow you to manage Webhooks.\n\nTo learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter"}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"WabaWebhook":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"user":{"allOf":[{"$ref":"#/components/schemas/ShortUser"}],"readOnly":true},"url":{"type":"string","format":"uri","description":"Remember to use `https://` URLs for your webhooks!\n\n**Note**: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}."},"on_incoming_message":{"type":"boolean","description":"Call this Webhook on every new Message coming from WhatsApp to Inbox.
This is how WhatsApp webhooks are called."},"on_outgoing_message":{"type":"boolean","description":"Call this Webhook on every new Message sent from Inbox to WhatsApp.
You should use this setting when integrating a system in which you want to have complete copies of all your conversations."},"on_assigned":{"type":"boolean","description":"Call this Webhook when existing Chat is assigned to this User or a new Message is posted to the Chat already assigned to this User.

You should set this when integrating a bot with this Webhook.
This is similar to how human Users are notified by desktop notifications. "},"on_message_echo":{"type":"boolean","description":"Call this Webhook when a message is sent from your WhatsApp Business number via the 360dialog messaging API, outside the Inbox.
The webhook receives the original Cloud API \"message_echoes\" payload, so your integration can keep a complete copy of the conversation. Messages sent through the Inbox API are not echoed here - use \"on outgoing message\" for those."},"headers":{"description":"Additional headers needed when calling a Webhook. Each header needs to be provided as a key-value pair in JSON format.
Useful for things like API keys with Authorization or other headers.

Example: {\"Authorization\": \"Token 1234567890qwertyuiop\"}"}},"required":["id","url","user"]},"ShortUser":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"username":{"type":"string","description":"Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.","pattern":"^[\\w.@+-]+$","maxLength":150},"url":{"type":"string","format":"uri","readOnly":true}},"required":["id","url","username"]}}},"paths":{"/api/v1/webhooks/waba/{id}/":{"put":{"operationId":"updateWabaWebhook","description":"Update a WhatsApp webhook: its URL, the events it is called for, and its headers.","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"description":"A unique integer value identifying this WABA webhook.","required":true}],"tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WabaWebhook"}}},"description":""}}}}}} ``` ## DELETE /api/v1/webhooks/waba/{id}/ > Deletes WABA Webhook permanently ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Webhooks","description":"These API endpoints allow you to manage Webhooks.\n\nTo learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter"}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}}},"paths":{"/api/v1/webhooks/waba/{id}/":{"delete":{"operationId":"deleteWabaWebhook","description":"Deletes WABA Webhook permanently","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"description":"A unique integer value identifying this WABA webhook.","required":true}],"tags":["Webhooks"],"responses":{"204":{"description":"No response body"}}}}}} ``` ## GET /api/v1/webhooks/waba/{id}/test/ > Test the WABA Webhook, by sending a mock "statuses" HTTP POST request to its target url ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Webhooks","description":"These API endpoints allow you to manage Webhooks.\n\nTo learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter"}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}}},"paths":{"/api/v1/webhooks/waba/{id}/test/":{"get":{"operationId":"testWabaWebhook","description":"Test the WABA Webhook, by sending a mock \"statuses\" HTTP POST request to its target url","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"description":"A unique integer value identifying this WABA webhook.","required":true}],"tags":["Webhooks"],"responses":{"200":{"description":"No response body"}}}}}} ``` --- # 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://docs.360dialog.com/docs/inbox/inbox-api/api-ref/webhooks.md?ask=&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.