smb_app_state_sync webhook reference

Updated: Jun 17, 2026

This reference describes trigger events and payload contents for the WhatsApp Business account smb_app_state_sync webhook.

The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider.

Triggers

• A partner synchronizes the WhatsApp Business app contacts of a business customer with a WhatsApp Business app phone number who the provider has onboarded.
• A business customer with a WhatsApp Business app phone number who has been onboarded by a partner adds a contact to their WhatsApp Business app contacts⁠.
• A business customer with a WhatsApp Business app phone number who has been onboarded by a partner removes a contact from their WhatsApp Business app contacts⁠.
• A business customer with a WhatsApp Business app phone number who has been onboarded by a partner edits a contact in their WhatsApp Business app contacts⁠.

Syntax

{  
  "object": "whatsapp_business_account",  
  "entry": [  
    {  
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",  
      "changes": [  
        {  
          "value": {  
            "messaging_product": "whatsapp",  
            "metadata": {  
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",  
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"  
            },  
            "state_sync": [  
              {  
                "type": "contact",  
                "contact": {  
                  "full_name": "<CONTACT_FULL_NAME>",  
                  "first_name": "<CONTACT_FIRST_NAME>",  
                  "phone_number": "<CONTACT_PHONE_NUMBER>"  
                },  
                "action": "<ACTION>",  
                "metadata": {  
                  "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>"  
                }  
              },  
              <!-- Additional contacts would follow, if any -->  
            ]  
          },  
          "field": "smb_app_state_sync"  
        }  
      ]  
    }  
  ]  
}

Parameters

Placeholder	Description	Example value
<ACTION> String	Indicates if the business customer added, edited, or deleted a contact from their WhatsApp Business app phone address book. Values can be: add — Indicates the WhatsApp Business app user added or edited a contact. remove — Indicates the WhatsApp Business app user removed a contact.	add
<BUSINESS_DISPLAY_PHONE_NUMBER> String	Business display phone number.	15550783881
<BUSINESS_PHONE_NUMBER_ID> String	Business phone number ID.	106540352242922
<CONTACT_FIRST_NAME> String	The contact's first name, as it appears in the business customer's WhatsApp Business app phone address book. Not included when the business customer removes a contact from their WhatsApp Business app phone address book.	Pablo
<CONTACT_FULL_NAME> String	The contact's full name, as it appears in the business customer's WhatsApp Business app phone address book. Not included when the business customer removes a contact from their WhatsApp Business app phone address book.	Pablo Morales
<CONTACT_PHONE_NUMBER>String	The contact's WhatsApp phone number.	16505551234
<WEBHOOK_TRIGGER_TIMESTAMP> Integer	Unix timestamp indicating when the webhook was triggered.	1739321024
<WHATSAPP_BUSINESS_ACCOUNT_ID> String	WhatsApp Business Account ID.	102290129340398

Example

{  
  "object": "whatsapp_business_account",  
  "entry": [  
    {  
      "id": "102290129340398",  
      "changes": [  
        {  
          "value": {  
            "messaging_product": "whatsapp",  
            "metadata": {  
              "display_phone_number": "15550783881",  
              "phone_number_id": "106540352242922"  
            },  
            "state_sync": [  
              {  
                "type": "contact",  
                "contact": {  
                  "full_name": "Pablo Morales",  
                  "first_name": "Pablo",  
                  "phone_number": "16505551234"  
                },  
                "action": "add",  
                "metadata": {  
                  "timestamp": "1739321024"  
                }  
              }  
            ]  
          },  
          "field": "smb_app_state_sync"  
        }  
      ]  
    }  
  ]  
}