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

# Webhooks

### What is Webhooks?

A webhook is a way for BotPenguin to automatically send data to your system the moment something happens — instead of your system having to keep checking for updates. You give BotPenguin a URL (your webhook endpoint), and BotPenguin sends event data to that URL as soon as the event occurs. This lets you automate tasks, keep your own systems updated in real time, and connect BotPenguin with other tools without manual work.

***

### When should you use this?

Use webhooks when:

* You want to be notified in real time when a WhatsApp message fails to deliver, or when your account's business verification, template quality, or capability status changes
* You want to track Instagram messaging events as they happen
* You want to monitor account-level events like message limit exhaustion, WhatsApp message limit exhaustion, plan expiry, or account freezes

***

### Benefits of Webhooks

* ⚡ Delivers event data to your system in real time, without polling
* 🔗 Connects BotPenguin with your own systems and workflows
* 🎯 Lets you subscribe only to the specific events you care about
* 🗂️ Covers WhatsApp, Instagram, and Account Level events from one central place
* 🛠️ Easy to edit, disable, or fully unsubscribe at any time

***

### How to Use Webhooks

#### A. Subscribing to Webhooks

1. Log into your BotPenguin account and go to "Developer" under the More section. Click on "Webhooks" section.

<figure><img src="/files/AiqsMibgA5lcIn9qP41z" alt=""><figcaption></figcaption></figure>

2. You'll see options to configure webhooks for multiple platforms.
3. Click on a card (WhatsApp, Instagram, or Account Level) to configure that section.
4. Click "Subscribe Webhooks."

<figure><img src="/files/GIoJJQnaO4bpKJue0yEb" alt=""><figcaption></figcaption></figure>

5. A pop-up will open. Enter your Webhook Endpoint and Verification Key, then select the bots you want the webhooks to be triggered for.

<figure><img src="/files/AK9F5qgbqa0U3VYzFyIi" alt=""><figcaption></figcaption></figure>

6. Once selected, the webhooks will be configured. From here, you can go into the specifics of each and turn on the individual ones you need.

***

#### B. WhatsApp Webhooks

Each section includes a "Search by Event Name" bar to quickly find a specific webhook, alongside an "Edit Webhook Subscription" button and an unsubscribe icon.

<figure><img src="/files/o3a7m88IrNf6uFV0KBQG" alt=""><figcaption></figcaption></figure>

There are several webhooks available for WhatsApp:

| Webhook                     | What it Tells You                                                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Failed Message              | When a message could not be delivered                                                                                            |
| Account Alerts              | When your account does not meet notability requirements. You can edit the display name and submit another request after 30 days. |
| Account Review Update       | When your account review request gets approved                                                                                   |
| Account Update              | Updates on the business verification of the WhatsApp account                                                                     |
| Business Capability Update  | Updates on the max daily limits per day                                                                                          |
| Business Status Update      | Updates the status of the business                                                                                               |
| Template Quality Update     | Updates on the template quality                                                                                                  |
| Template Status Update      | The approval status of a submitted template                                                                                      |
| Messages                    | Messages that are received                                                                                                       |
| Phone Number Name Update    | When the name related to a phone number is updated                                                                               |
| Phone Number Quality Update | The plan quality of a new user                                                                                                   |
| Security                    | Information regarding the security of PINs                                                                                       |
| Template Category Update    | Updates the template category                                                                                                    |
| All Meta Webhooks           | A single event that fires for all Meta webhook types together, instead of subscribing to each individually                       |

* Each event row has its own Status toggle and a "Test" button, so you can trigger a sample event to confirm your endpoint is receiving it correctly.
* To edit any webhook, click "Edit Webhook Subscription."
* To disconnect a single webhook, turn off its status. To disconnect all webhooks at once, click "Unsubscribe Webhooks" and confirm.

#### C. Instagram Webhooks

<figure><img src="/files/XGpFoNXA6q1KI43VoiAm" alt=""><figcaption></figcaption></figure>

Instagram webhooks work in a similar manner to WhatsApp webhooks, with their own set of events:

<table data-search="false"><thead><tr><th>Webhook</th><th>What it Tells You</th></tr></thead><tbody><tr><td>Failed Message</td><td>When a message could not be delivered</td></tr><tr><td>Auto-Reply Delivery</td><td>When an automated reply has been delivered</td></tr><tr><td>Comments</td><td>New comments received on your Instagram content</td></tr><tr><td>Live Comments</td><td>Comments received during a live video</td></tr><tr><td>Mentions</td><td>When your account is mentioned</td></tr><tr><td>Message Reactions</td><td>When a user reacts to a message</td></tr><tr><td>Messages</td><td>Messages that are received</td></tr><tr><td>Messaging Handover</td><td>When a conversation is handed over between the bot and a human agent</td></tr><tr><td>Messaging Postbacks</td><td>When a user interacts with a postback button</td></tr><tr><td>Message Seen</td><td>When a sent message has been seen by the user</td></tr></tbody></table>

* Each event row has its own Status toggle and a "Test" button, so you can trigger a sample event to confirm your endpoint is receiving it correctly.
* To edit any webhook subscription, click "Edit Webhook Subscription."
* To disconnect a single webhook, turn off its status. To disconnect all webhooks at once, click "Unsubscribe Webhooks" and confirm.

***

#### D. Account Level Webhooks

<figure><img src="/files/n955ZFPDxexsUdJjjNvt" alt=""><figcaption></figcaption></figure>

| Webhook                          | Use Case                                                                                     |
| -------------------------------- | -------------------------------------------------------------------------------------------- |
| Message Limit Exhausted          | Notifies you when your available message quota has been fully used                           |
| WhatsApp Message Limit Exhausted | Notifies you specifically when your WhatsApp message quota has been fully used               |
| Plan Expired                     | Sends a notification when your subscription plan has expired                                 |
| Account Freeze                   | Notifies you when your account is temporarily frozen due to non-payment or policy violations |

* Each event row has its own Status toggle and a "Test" button, so you can trigger a sample event to confirm your endpoint is receiving it correctly.

***

### Best Practices

> 💡 Only subscribe to the specific webhooks you actually plan to act on, to keep your endpoint's traffic manageable

> ⚠️ Make sure your webhook endpoint is publicly accessible and returns a valid response, or deliveries may fail

> 🎯 Use the Verification Key to confirm incoming payloads are genuinely from BotPenguin before processing them

> 🚀 Turn off individual webhooks you no longer need instead of unsubscribing entirely, if you still need others active

***

### Troubleshooting

<details>

<summary>Webhook events aren't arriving at my endpoint</summary>

Confirm the Webhook Endpoint URL is correct, publicly accessible, and that the specific webhook's status is turned on.

</details>

<details>

<summary>"Subscribe Webhooks" pop-up won't save</summary>

Check that both the Webhook Endpoint and Verification Key fields are filled in, and that at least one bot is selected.

</details>

<details>

<summary>Some WhatsApp/Instagram events fire but others don't</summary>

Each webhook type is toggled individually — confirm the specific event you're expecting is turned on, not just the overall subscription.

</details>

<details>

<summary>Account Level webhooks not triggering as expected</summary>

Confirm the relevant bots are selected under the Account Level configuration, and that the triggering condition (e.g. quota percentage) is set correctly.

</details>

***

### FAQs

<details>

<summary>What are webhooks in BotPenguin?</summary>

Webhooks are automated callbacks that notify your system in real time when specific events occur on BotPenguin, such as message delivery failures or subscription changes.

</details>

<details>

<summary>Which platforms do these webhooks support?</summary>

This section covers webhooks for WhatsApp, Instagram, and Account Level events.

</details>

<details>

<summary>What kind of events can trigger a webhook?</summary>

Events include failed message delivery, account and template status updates, message limit exhaustion, plan expiry, and account freezes, among others.

</details>

<details>

<summary>Are webhooks real-time?</summary>

Yes. BotPenguin webhooks are designed to send event notifications immediately as they occur.

</details>

<details>

<summary>What format does the webhook payload use?</summary>

Webhook payloads are sent in JSON format, containing structured data about the triggered event.

</details>

<details>

<summary>How can I test if my webhook is working?</summary>

BotPenguin provides testing options within the webhook configuration section, allowing you to simulate event triggers and validate your endpoint setup.

</details>

<details>

<summary>What should I do if my webhook endpoint fails?</summary>

Ensure your endpoint URL is active and accessible. BotPenguin may retry failed deliveries, but persistent failures will require you to debug and update your configuration.

</details>

***

### Support

If everything is correct and you are still unable to move forward, write to us at <support@botpenguin.com>. We will respond back within 48 business hours.