[{"data":1,"prerenderedAt":680},["ShallowReactive",2],{"help-article-integrations-webhooks-receiving":3,"help-siblings-integrations":647},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"category":5,"order":10,"difficulty":11,"time_to_complete":12,"related":13,"body":17,"_type":641,"_id":642,"_source":643,"_file":644,"_stem":645,"_extension":646},"\u002Fhelp\u002Fintegrations\u002Fwebhooks-receiving","integrations",false,"","Receiving messages via webhooks","How to set up outbound webhooks to receive real-time notifications when messages arrive, are delivered, or read.",3,"intermediate","5 minutes",[14,15,16],"\u002Fhelp\u002Fintegrations\u002Fapi-overview","\u002Fhelp\u002Fintegrations\u002Fwebhook-events","\u002Fhelp\u002Fsettings\u002Fmanaging-accounts",{"type":18,"children":19,"toc":629},"root",[20,28,34,41,46,76,82,164,170,352,358,370,376,389,394,419,430,436,480,486,491,516,522,547,570,576],{"type":21,"tag":22,"props":23,"children":25},"element","h1",{"id":24},"receiving-messages-via-webhooks",[26],{"type":27,"value":8},"text",{"type":21,"tag":29,"props":30,"children":31},"p",{},[32],{"type":27,"value":33},"Webhooks send real-time HTTP notifications to your server when events happen in AIsoule.",{"type":21,"tag":35,"props":36,"children":38},"h2",{"id":37},"what-are-webhooks",[39],{"type":27,"value":40},"What are webhooks?",{"type":21,"tag":29,"props":42,"children":43},{},[44],{"type":27,"value":45},"Instead of polling the API repeatedly, webhooks push data to your server instantly when:",{"type":21,"tag":47,"props":48,"children":49},"ul",{},[50,56,61,66,71],{"type":21,"tag":51,"props":52,"children":53},"li",{},[54],{"type":27,"value":55},"A new message arrives",{"type":21,"tag":51,"props":57,"children":58},{},[59],{"type":27,"value":60},"A message is delivered or read",{"type":21,"tag":51,"props":62,"children":63},{},[64],{"type":27,"value":65},"A contact is created or updated",{"type":21,"tag":51,"props":67,"children":68},{},[69],{"type":27,"value":70},"A campaign completes",{"type":21,"tag":51,"props":72,"children":73},{},[74],{"type":27,"value":75},"An agent transfer happens",{"type":21,"tag":35,"props":77,"children":79},{"id":78},"setting-up-a-webhook",[80],{"type":27,"value":81},"Setting up a webhook",{"type":21,"tag":83,"props":84,"children":85},"ol",{},[86,97,107,155],{"type":21,"tag":51,"props":87,"children":88},{},[89,91],{"type":27,"value":90},"Go to ",{"type":21,"tag":92,"props":93,"children":94},"strong",{},[95],{"type":27,"value":96},"Settings → Webhooks",{"type":21,"tag":51,"props":98,"children":99},{},[100,102],{"type":27,"value":101},"Click ",{"type":21,"tag":92,"props":103,"children":104},{},[105],{"type":27,"value":106},"\"New Webhook\"",{"type":21,"tag":51,"props":108,"children":109},{},[110,112],{"type":27,"value":111},"Configure:\n",{"type":21,"tag":47,"props":113,"children":114},{},[115,125,135,145],{"type":21,"tag":51,"props":116,"children":117},{},[118,123],{"type":21,"tag":92,"props":119,"children":120},{},[121],{"type":27,"value":122},"Name",{"type":27,"value":124}," — Descriptive name (e.g., \"CRM Sync\")",{"type":21,"tag":51,"props":126,"children":127},{},[128,133],{"type":21,"tag":92,"props":129,"children":130},{},[131],{"type":27,"value":132},"URL",{"type":27,"value":134}," — Your server endpoint (must be HTTPS)",{"type":21,"tag":51,"props":136,"children":137},{},[138,143],{"type":21,"tag":92,"props":139,"children":140},{},[141],{"type":27,"value":142},"Events",{"type":27,"value":144}," — Select which events to receive",{"type":21,"tag":51,"props":146,"children":147},{},[148,153],{"type":21,"tag":92,"props":149,"children":150},{},[151],{"type":27,"value":152},"Secret",{"type":27,"value":154}," — Auto-generated HMAC secret for verification",{"type":21,"tag":51,"props":156,"children":157},{},[158,159],{"type":27,"value":101},{"type":21,"tag":92,"props":160,"children":161},{},[162],{"type":27,"value":163},"Save",{"type":21,"tag":35,"props":165,"children":167},{"id":166},"available-events",[168],{"type":27,"value":169},"Available events",{"type":21,"tag":171,"props":172,"children":173},"table",{},[174,193],{"type":21,"tag":175,"props":176,"children":177},"thead",{},[178],{"type":21,"tag":179,"props":180,"children":181},"tr",{},[182,188],{"type":21,"tag":183,"props":184,"children":185},"th",{},[186],{"type":27,"value":187},"Event",{"type":21,"tag":183,"props":189,"children":190},{},[191],{"type":27,"value":192},"Triggered when",{"type":21,"tag":194,"props":195,"children":196},"tbody",{},[197,216,233,250,267,284,301,318,335],{"type":21,"tag":179,"props":198,"children":199},{},[200,211],{"type":21,"tag":201,"props":202,"children":203},"td",{},[204],{"type":21,"tag":205,"props":206,"children":208},"code",{"className":207},[],[209],{"type":27,"value":210},"message.incoming",{"type":21,"tag":201,"props":212,"children":213},{},[214],{"type":27,"value":215},"New message received from customer",{"type":21,"tag":179,"props":217,"children":218},{},[219,228],{"type":21,"tag":201,"props":220,"children":221},{},[222],{"type":21,"tag":205,"props":223,"children":225},{"className":224},[],[226],{"type":27,"value":227},"message.sent",{"type":21,"tag":201,"props":229,"children":230},{},[231],{"type":27,"value":232},"Message sent successfully",{"type":21,"tag":179,"props":234,"children":235},{},[236,245],{"type":21,"tag":201,"props":237,"children":238},{},[239],{"type":21,"tag":205,"props":240,"children":242},{"className":241},[],[243],{"type":27,"value":244},"message.delivered",{"type":21,"tag":201,"props":246,"children":247},{},[248],{"type":27,"value":249},"Message delivered to recipient",{"type":21,"tag":179,"props":251,"children":252},{},[253,262],{"type":21,"tag":201,"props":254,"children":255},{},[256],{"type":21,"tag":205,"props":257,"children":259},{"className":258},[],[260],{"type":27,"value":261},"message.read",{"type":21,"tag":201,"props":263,"children":264},{},[265],{"type":27,"value":266},"Message read by recipient",{"type":21,"tag":179,"props":268,"children":269},{},[270,279],{"type":21,"tag":201,"props":271,"children":272},{},[273],{"type":21,"tag":205,"props":274,"children":276},{"className":275},[],[277],{"type":27,"value":278},"message.failed",{"type":21,"tag":201,"props":280,"children":281},{},[282],{"type":27,"value":283},"Message delivery failed",{"type":21,"tag":179,"props":285,"children":286},{},[287,296],{"type":21,"tag":201,"props":288,"children":289},{},[290],{"type":21,"tag":205,"props":291,"children":293},{"className":292},[],[294],{"type":27,"value":295},"contact.created",{"type":21,"tag":201,"props":297,"children":298},{},[299],{"type":27,"value":300},"New contact added",{"type":21,"tag":179,"props":302,"children":303},{},[304,313],{"type":21,"tag":201,"props":305,"children":306},{},[307],{"type":21,"tag":205,"props":308,"children":310},{"className":309},[],[311],{"type":27,"value":312},"contact.updated",{"type":21,"tag":201,"props":314,"children":315},{},[316],{"type":27,"value":317},"Contact data changed",{"type":21,"tag":179,"props":319,"children":320},{},[321,330],{"type":21,"tag":201,"props":322,"children":323},{},[324],{"type":21,"tag":205,"props":325,"children":327},{"className":326},[],[328],{"type":27,"value":329},"campaign.completed",{"type":21,"tag":201,"props":331,"children":332},{},[333],{"type":27,"value":334},"Campaign finished sending",{"type":21,"tag":179,"props":336,"children":337},{},[338,347],{"type":21,"tag":201,"props":339,"children":340},{},[341],{"type":21,"tag":205,"props":342,"children":344},{"className":343},[],[345],{"type":27,"value":346},"transfer.created",{"type":21,"tag":201,"props":348,"children":349},{},[350],{"type":27,"value":351},"Agent transfer initiated",{"type":21,"tag":35,"props":353,"children":355},{"id":354},"webhook-payload-format",[356],{"type":27,"value":357},"Webhook payload format",{"type":21,"tag":359,"props":360,"children":365},"pre",{"className":361,"code":363,"language":364,"meta":7},[362],"language-json","{\n  \"event\": \"message.incoming\",\n  \"timestamp\": \"2026-05-29T10:30:00Z\",\n  \"data\": {\n    \"message_id\": \"wamid.xxx\",\n    \"from\": \"+919876543210\",\n    \"contact_name\": \"John Doe\",\n    \"type\": \"text\",\n    \"text\": \"Hello, I need help with my order\",\n    \"whatsapp_account_id\": \"uuid\"\n  }\n}\n","json",[366],{"type":21,"tag":205,"props":367,"children":368},{"__ignoreMap":7},[369],{"type":27,"value":363},{"type":21,"tag":35,"props":371,"children":373},{"id":372},"verifying-webhook-signatures",[374],{"type":27,"value":375},"Verifying webhook signatures",{"type":21,"tag":29,"props":377,"children":378},{},[379,381,387],{"type":27,"value":380},"Every webhook request includes an HMAC-SHA256 signature in the ",{"type":21,"tag":205,"props":382,"children":384},{"className":383},[],[385],{"type":27,"value":386},"X-Webhook-Signature",{"type":27,"value":388}," header.",{"type":21,"tag":29,"props":390,"children":391},{},[392],{"type":27,"value":393},"To verify:",{"type":21,"tag":83,"props":395,"children":396},{},[397,402,407],{"type":21,"tag":51,"props":398,"children":399},{},[400],{"type":27,"value":401},"Get the raw request body",{"type":21,"tag":51,"props":403,"children":404},{},[405],{"type":27,"value":406},"Compute HMAC-SHA256 using your webhook secret",{"type":21,"tag":51,"props":408,"children":409},{},[410,412,417],{"type":27,"value":411},"Compare with the ",{"type":21,"tag":205,"props":413,"children":415},{"className":414},[],[416],{"type":27,"value":386},{"type":27,"value":418}," header",{"type":21,"tag":359,"props":420,"children":425},{"className":421,"code":423,"language":424,"meta":7},[422],"language-python","import hmac, hashlib\n\ndef verify_signature(body, signature, secret):\n    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(expected, signature)\n","python",[426],{"type":21,"tag":205,"props":427,"children":428},{"__ignoreMap":7},[429],{"type":27,"value":423},{"type":21,"tag":35,"props":431,"children":433},{"id":432},"requirements-for-your-endpoint",[434],{"type":27,"value":435},"Requirements for your endpoint",{"type":21,"tag":47,"props":437,"children":438},{},[439,451,463,475],{"type":21,"tag":51,"props":440,"children":441},{},[442,444,449],{"type":27,"value":443},"Must respond with ",{"type":21,"tag":92,"props":445,"children":446},{},[447],{"type":27,"value":448},"HTTP 200",{"type":27,"value":450}," within 5 seconds",{"type":21,"tag":51,"props":452,"children":453},{},[454,456,461],{"type":27,"value":455},"Must accept ",{"type":21,"tag":92,"props":457,"children":458},{},[459],{"type":27,"value":460},"POST",{"type":27,"value":462}," requests",{"type":21,"tag":51,"props":464,"children":465},{},[466,468,473],{"type":27,"value":467},"Must use ",{"type":21,"tag":92,"props":469,"children":470},{},[471],{"type":27,"value":472},"HTTPS",{"type":27,"value":474}," (HTTP not supported)",{"type":21,"tag":51,"props":476,"children":477},{},[478],{"type":27,"value":479},"Should be idempotent (same event may be sent twice)",{"type":21,"tag":35,"props":481,"children":483},{"id":482},"retry-policy",[484],{"type":27,"value":485},"Retry policy",{"type":21,"tag":29,"props":487,"children":488},{},[489],{"type":27,"value":490},"If your endpoint doesn't respond with 200:",{"type":21,"tag":47,"props":492,"children":493},{},[494,506,511],{"type":21,"tag":51,"props":495,"children":496},{},[497,499,504],{"type":27,"value":498},"AIsoule retries ",{"type":21,"tag":92,"props":500,"children":501},{},[502],{"type":27,"value":503},"3 times",{"type":27,"value":505}," with exponential backoff",{"type":21,"tag":51,"props":507,"children":508},{},[509],{"type":27,"value":510},"Delays: 10 seconds, 60 seconds, 5 minutes",{"type":21,"tag":51,"props":512,"children":513},{},[514],{"type":27,"value":515},"After 3 failures, the webhook is marked as failing",{"type":21,"tag":35,"props":517,"children":519},{"id":518},"testing-webhooks",[520],{"type":27,"value":521},"Testing webhooks",{"type":21,"tag":29,"props":523,"children":524},{},[525,527,536,538,545],{"type":27,"value":526},"Use tools like ",{"type":21,"tag":528,"props":529,"children":533},"a",{"href":530,"rel":531},"https:\u002F\u002Fwebhook.site",[532],"nofollow",[534],{"type":27,"value":535},"webhook.site",{"type":27,"value":537}," or ",{"type":21,"tag":528,"props":539,"children":542},{"href":540,"rel":541},"https:\u002F\u002Fngrok.com",[532],[543],{"type":27,"value":544},"ngrok",{"type":27,"value":546}," to test locally:",{"type":21,"tag":83,"props":548,"children":549},{},[550,555,560,565],{"type":21,"tag":51,"props":551,"children":552},{},[553],{"type":27,"value":554},"Get a temporary HTTPS URL from webhook.site",{"type":21,"tag":51,"props":556,"children":557},{},[558],{"type":27,"value":559},"Set it as your webhook URL in AIsoule",{"type":21,"tag":51,"props":561,"children":562},{},[563],{"type":27,"value":564},"Send a test message to your WhatsApp number",{"type":21,"tag":51,"props":566,"children":567},{},[568],{"type":27,"value":569},"See the webhook payload arrive in real-time",{"type":21,"tag":35,"props":571,"children":573},{"id":572},"tips",[574],{"type":27,"value":575},"Tips",{"type":21,"tag":83,"props":577,"children":578},{},[579,589,599,609,619],{"type":21,"tag":51,"props":580,"children":581},{},[582,587],{"type":21,"tag":92,"props":583,"children":584},{},[585],{"type":27,"value":586},"Respond quickly",{"type":27,"value":588}," — Process asynchronously, respond 200 immediately",{"type":21,"tag":51,"props":590,"children":591},{},[592,597],{"type":21,"tag":92,"props":593,"children":594},{},[595],{"type":27,"value":596},"Handle duplicates",{"type":27,"value":598}," — Use message_id to deduplicate",{"type":21,"tag":51,"props":600,"children":601},{},[602,607],{"type":21,"tag":92,"props":603,"children":604},{},[605],{"type":27,"value":606},"Monitor failures",{"type":27,"value":608}," — Check webhook status in Settings → Webhooks",{"type":21,"tag":51,"props":610,"children":611},{},[612,617],{"type":21,"tag":92,"props":613,"children":614},{},[615],{"type":27,"value":616},"Use the secret",{"type":27,"value":618}," — Always verify signatures in production",{"type":21,"tag":51,"props":620,"children":621},{},[622,627],{"type":21,"tag":92,"props":623,"children":624},{},[625],{"type":27,"value":626},"Log everything",{"type":27,"value":628}," — Store raw payloads for debugging",{"title":7,"searchDepth":630,"depth":630,"links":631},2,[632,633,634,635,636,637,638,639,640],{"id":37,"depth":630,"text":40},{"id":78,"depth":630,"text":81},{"id":166,"depth":630,"text":169},{"id":354,"depth":630,"text":357},{"id":372,"depth":630,"text":375},{"id":432,"depth":630,"text":435},{"id":482,"depth":630,"text":485},{"id":518,"depth":630,"text":521},{"id":572,"depth":630,"text":575},"markdown","content:help:integrations:webhooks-receiving.md","content","help\u002Fintegrations\u002Fwebhooks-receiving.md","help\u002Fintegrations\u002Fwebhooks-receiving","md",[648,650,653,656,659,662,665,668,671,673,674,677],{"_path":14,"title":649},"REST API overview and authentication",{"_path":651,"title":652},"\u002Fhelp\u002Fintegrations\u002Fapi-rate-limits","API rate limits and best practices",{"_path":654,"title":655},"\u002Fhelp\u002Fintegrations\u002Fcustom-js-actions","Using the JavaScript VM for custom actions",{"_path":657,"title":658},"\u002Fhelp\u002Fintegrations\u002Ferror-codes","Error codes reference",{"_path":660,"title":661},"\u002Fhelp\u002Fintegrations\u002Fpayment-gateway","Payment gateway setup (Razorpay\u002FStripe)",{"_path":663,"title":664},"\u002Fhelp\u002Fintegrations\u002Fproduct-catalog-sync","Product catalog sync from Meta",{"_path":666,"title":667},"\u002Fhelp\u002Fintegrations\u002Fsending-messages-api","Sending messages via API",{"_path":669,"title":670},"\u002Fhelp\u002Fintegrations\u002Fsending-messages-api-templates","Sending messages via API (advanced)",{"_path":15,"title":672},"Webhook event types reference",{"_path":4,"title":8},{"_path":675,"title":676},"\u002Fhelp\u002Fintegrations\u002Fwoocommerce","WooCommerce integration setup",{"_path":678,"title":679},"\u002Fhelp\u002Fintegrations\u002Fzapier-pabbly","Connecting with Zapier and Pabbly Connect",1780423187519]