Skip to main content

automatic_events webhook reference | Developer Documentation

automatic_events webhook reference

Updated: Nov 5, 2025
This reference describes trigger events and payload contents for the WhatsApp Business Account automatic_events webhook.
The automatic_events webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to Automatic Events reporting.

Triggers

    A lead event is detected in a chat thread between a business and user who has messaged the business via a Click to WhatsApp Ad.A purchase event is detected in a chat thread between a business and user who has messaged the business via a Click to WhatsApp Ad.

    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>"
            },
            "automatic_events": [
              {
                "id": "<WHATSAPP_MESSAGE_ID>",
                "event_name": "<EVENT_NAME>",
                "timestamp": <WEBHOOK_TRIGGER_TIMESTAMP>,
                "ctwa_clid": "<AD_CLICK_ID>",

                <!-- Only included for purchase events -->
                "custom_data": {
                  "currency": "<CURRENCY_CODE>",
                  "value": <AMOUNT>
                }

              }
            ]
          },
          "field": "automatic_events"
        }
      ]
    }
  ]
}
    Parameters
    

    

    



Placeholder 

Description 

Example value 




    

    <AD_CLICK_ID>
    

    String
    


    

    Click to WhatsApp ad click ID.
    

    The ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status (WhatsApp Status ad placements⁠?).
    


    

    Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50
    



    

    <AMOUNT>
    

    String
    


    

    Purchase amount, calculated as product price multiplied by 1000.
    


    

    25000
    



    

    <BUSINESS_DISPLAY_PHONE_NUMBER>
    

    String
    


    

    Business display phone number.
    


    

    15550783881
    



    

    <BUSINESS_PHONE_NUMBER_ID>
    

    String
    


    

    Business phone number ID.
    


    

    106540352242922
    



    

    <CURRENCY_CODE>
    

    String
    


    

    Currency code.
    


    

    USD
    



    

    <EVENT_NAME>
    

    String
    


    

    Event name. Values can be:
    

      LeadSubmitted —- Indicates a lead event.Purchase —- Indicates a purchase event.
      


      

      Purchase
      



      

      <WEBHOOK_TRIGGER_TIMESTAMP>
      

      Integer
      


      

      Unix timestamp indicating when the webhook was triggered.
      


      

      1739321024
      



      

      <WHATSAPP_MESSAGE_ID>
      

      String
      


      

      WhatsApp message ID.
      


      

      wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=
      



      

      <WHATSAPP_BUSINESS_ACCOUNT_ID>
      

      String
      


      

      WhatsApp Business Account ID.
      


      

      102290129340398
      

      

      

      

      Examples
      

      

      

      

      Lead gen event
      

      

      {
      
"object":
      
"whatsapp_business_account",
      
"entry":
      
[
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "automatic_events": [
              {
                "id": "wamid.HBgLMTIwNjY3NzQ3OTgVAgASGBQzQUY3MDVCQzFBODE5ODU4MUZEOQA=",
                "event_name": "LeadSubmitted",
                "timestamp": 1749069089,
                "ctwa_clid": "Afc3nYt4TTydumlFFsatFz8bR2yHCtVA92Veu_zDE4DgAI-QqCwM6eC3-K3lTGHRiLxRTVXFEsdyKQQSa-2obZyuGBq_EYypt_OwbMihBV0pbUoRmrGnEjwFTHop-Px0TfA"
              }
            ]
          },
          "field": "automatic_events"
        }
      ]
    }
  ]
}
      Purchase event
      

      

      {
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "automatic_events": [
              {
                "id": "wamid.HBgLMTIwNjY3NzQ3OTgVAgARGBIwRkU4NDI5Nzk3RjZDMzE2RUMA",
                "event_name": "Purchase",
                "timestamp": 1749069131,
                "ctwa_clid": "Afc3nYt4TTydumlFFsatFz8bR2yHCtVA92Veu_zDE4DgAI-QqCwM6eC3-K3lTGHRiLxRTVXFEsdyKQQSa-2obZyuGBq_EYypt_OwbMihBV0pbUoRmrGnEjwFTHop-Px0TfA",
                "custom_data": {
                  "currency": "USD",
                  "value": 25000
                }
              }
            ]
          },
          "field": "automatic_events"
        }
      ]
    }
  ]
}
      
    
              
      
    
      

            
      
        
      
    
      

    
      

    
    
      
        
      
             Back to top