Webhooks

New Webhooks section in integrations providing ability to send specific events to these webhooks.

The Webhooks feature allows you to subscribe to real-time events triggered by the Gupshup platform and receive updates on your callback URL. This enables you to automate your workflows, monitor system-level changes, and track message delivery statuses as they happen.

How to configure Webhooks?

  • Log into your Gupshup Console.
  • Navigate to your App > Integration > Webhooks.
  • Click on create Webhook.
  • Choose the module and respective events:
    • WhatsApp
      • Profile (Account)
      • Template
    • Campaign Manager and API
      • Delivery events
  • Add your Callback URL and save.

_Important Note: You can configure only 1 URL for Delivery Events. Additional webhooks created will update the URL and events will be sent to the latest URL saved. _

Once configured, the Gupshup platform will begin pushing events to your callback URL via HTTPS POST requests.




You can configure your app to receive the following categories of webhook events:

  1. Profile Events
  2. Template Events
  3. Delivery Events

Event Types

  1. Profile Events (Account Events)
    Profile or Account Events are triggered when a change or update occurs in your WhatsApp Business Account (WABA), such as:
    1. Business review status
    2. Policy violations
    3. WABA restrictions
    4. Tier changes
    5. Capability updates

🛠️ Event Types

Event TypeDescription
review-eventTriggered when WABA is approved or rejected.
status-eventTriggered when your WABA's status changes (e.g., disabled, restricted, verified).
pndn-eventStatus updates of submitted phone number or display name.
tier-eventNotification for quality-related tier status changes (e.g., TIER_1K to TIER_10K).
capability-eventMessaging capability updates (e.g., maxDailyConversationPerPhone).

🧾 Sample Payload

  • Review event

`{ "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "review-event", "payload": { "status": "approved", "actionDate": "January 31,2021" } } }`

  • status-event(account violation)

`{ "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "status-event", "payload": { "status": "ACCOUNT_VIOLATION", "violation_type": "GAMBLING" } } }`

  • status-event(account disable)

`{ "app": "<appname>", "appId": "<id>", "timestamp": 1713531530035, "version": 2, "type": "account-event", "payload": { "type": "status-event", "payload": { "status": "DISABLE", "actionDate": "February28,2024" } } }`

  • status-event(account restriction)

`{ "app":"appname", "timestamp":1636986446609, "version":2, "type":"account-event", "phone":"9180xxxxxxxx", "payload":{ "type":"status-event", "payload":{ "status":"ACCOUNT_RESTRICTED", "restrictionInfo":[ { "restrictionType":"RESTRICTION_ADD_PHONE_NUMBER_ACTION", "expiration":1636986446609 }, { "restrictionType":"RESTRICTED_BIZ_INITIATED_MESSAGING", "expiration":1636986446609 }, { "restrictionType":"RESTRICTED_CUSTOMER_INITIATED_MESSAGING", "expiration":1636986446609 } ] } } }`

  • status-event(reinstate)

`{ "app": "ShipxxxxxxxxxxxxxxxxxxWapp", "appId": "e4c9dbe0-b1ef-4add-97a2-a8fdba0666ad", "phone": "918xxxxxxxxx2", "timestamp": 1717061550941, "version": 2, "type": "account-event", "payload": { "type": "status-event", "payload": { "status": "REINSTATE", "actionDate": "30 May 2024" } } }`

  • pndn-event

`{ "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "pndn-event", "payload": { "status": "approved/rejected", "rejectedReason": "INVALID_FORMAT" } } }`

  • tier-event

`{ "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "tier-event", "payload": { "event": "onboarding/ upgrade/ downgrade /unflagged/ flagged", "oldLimit": "TIER_10K", "currentLimit": "TIER_100K" } } }`

  • capability-event

`{ "app":"appname", "timestamp":1636986446609, "version":2, "type":"account-event", "payload":{ "type":"capability-event", "payload":{ "maxDailyConversationPerPhone":100, "maxPhoneNumbersPerBusiness":100 } } }`


Key : Description

review-event : Triggered when the submitted WABA is approved or rejected. Possible values: APPROVED, REJECTED

status-event : Triggered when the status of the WABA changes. Possible values:

  • ACCOUNT_VIOLATION: WABA flagged due to policy violation.
  • ACCOUNT_DISABLE: WABA has been disabled.
  • ACCOUNT_VERIFIED: App upgraded from Sandbox to Live.
  • ACCOUNT_RESTRICTED: WABA restricted due to policy issues. Restriction types: • RESTRICTION_ADD_PHONE_NUMBER_ACTION • RESTRICTED_BIZ_INITIATED_MESSAGING • RESTRICTED_CUSTOMER_INITIATED_MESSAGING (Includes restriction expiry)

pndn-event : Triggered when the status of a submitted Phone Number or Display Name is updated. Possible values:

  • INVALID_FORMAT
  • NAME_END_CLIENT_VIOLATION
  • NAME_FORMAT_UNACCEPTABLE
  • NAME_NOT_CONSISTENT
  • NAME_INDIVIDUAL_ISSUE
  • NAME_ENDCLIENT_NOTRELATED

tier-event : Notifies changes in the messaging tier of a phone number. Event values: ONBOARDING, UPGRADE, DOWNGRADE, UNFLAGGED, FLAGGED Tier levels: TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED

capability-event : Provides updates on WABA's messaging capabilities. Includes:

  • maxDailyConversationPerPhone: Max users a phone number can message daily.
  • maxPhoneNumbersPerBusiness: Max phone numbers allowed in a business. (Minimum limit shown across phone numbers)

waba_id : Unique identifier of the WhatsApp Business Account (WABA).

owner_business_id : Meta Business Manager ID that owns the WABA and associated assets.

ad_account_id : Meta Ad Account ID linked for running Click-to-WhatsApp ads or templates in MM Lite.


  1. Template Events
    Template events notify you of the status or category of your WhatsApp message templates. These are generated automatically by Gupshup when any change occurs.

📌 Event Types

TypeDescription
status-updateWhen template status changes (e.g., approved, rejected, paused).
category-updateWhen WhatsApp migrates templates to new categories.
quality-updateNotifies the quality score assigned to templates by WhatsApp.

🔁 Automatic Template Category Migration
Starting June 1, 2024, if a template is incorrectly categorized, you will receive two events:

  • A category alert with current and correct category.
  • A final update once the change is applied.

✅ First Payload (Alert)

{ "type": "template-event", "payload": { "type": "category-update", "category": { "current": "MARKETING", "correct": "UTILITY" } } }

📤 Second Payload (Confirmed Update)
json

{ "type": "template-event", "payload": { "type": "category-update", "category": { "old": "MARKETING", "new": "UTILITY" } } }

🧾 Sample status-update Payload

{ "type": "template-event", "payload": { "type": "status-update", "id": "4dacef15-6c04-12db-b393-6190ac567eff", "status": "approved", "elementName": "order_update", "languageCode": "en_US" } }

  1. Delivery Events (Real-Time Message Status)
    Delivery webhooks notify you in real-time about message delivery statuses for Campaigns and API sent messages over WhatsApp. These events help track:
    1. Message sent
    2. Delivered
    3. Read
    4. Failed

Each event includes metadata about the conversation and pricing category (marketing, utility, authentication).

🧾 Sample Payload

{ "srcAddr": "919898989898", "channel": "WHATSAPP", "hsmTemplateId": "6330963", "externalId": "4873914210717831261-128116432999904428", "cause": "SENT", "errorCode": "025", "destAddr": "91XXXXXXXXXX", "eventType": "SENT", "eventTs": 1680527479000, "conversation": { "expiration_timestamp": 1680613560, "origin": { "type": "marketing" }, "id": "072a7f95683c6c2bffef5655c706c50d" }, "pricing": { "category": "marketing" } }

🔑 Key Parameters Explained

KeyDescription
externalIdUnique ID for each message request
eventTypeStatus of message (SENT, DELIVERED, READ, FAILED)
srcAddrBusiness phone number
destAddrRecipient phone number
conversation.idUnique conversation ID
conversation.expiration_timestampExpiry of 24-hour customer service window
pricing.categoryFinal category of the message