Z-API Configuration and Webhook Setup

Why this is important

To ensure consistent and reliable configuration of Z-API and its webhook integrations, enabling smooth message flow between WhatsApp and automation systems (e.g., n8n, Zapier, custom backends). Proper setup avoids delivery errors, missed messages, and integration failures.

---

Definitions

• Z-API: An unofficial WhatsApp API service that simulates WhatsApp Web to send/receive messages programmatically.
  
  

• Webhook: An HTTP callback used by Z-API to deliver incoming messages or status updates to your server/automation platform.
  
  

• Instance: A unique Z-API account configuration tied to one WhatsApp number.
  
  

• Security Token: An authentication string provided by Z-API to secure API requests.

---

Procedure

Title

Z-API Configuration and Webhook Setup

---

Scope (Description)

This SOP applies to all technical staff responsible for configuring Z-API instances and webhooks to ensure WhatsApp message delivery and reception. It covers initial setup, authentication, and webhook endpoint configuration.

---

Purpose (Why this is important)

To establish a standardized process for setting up Z-API and webhooks, ensuring reliable and secure integration between WhatsApp and downstream automation systems.

---

Procedure (Step-by-step)

1. Create a Z-API Account
   
   

   • Go to the Z-API dashboard.
     
     

   • Register and create a new instance.
     
     

   • Note the Instance ID and Token generated.
     
     

2. Link WhatsApp Number
   
   

   • Open WhatsApp on your phone → Linked Devices.
     
     

   • Scan the QR code displayed on Z-API dashboard.
     
     

   • Verify the connection is active (status: Connected).
     
     

3. Configure Webhook URL
   
   

   • In the Z-API dashboard, navigate to Webhook Settings.
     
     

   • Enter your webhook endpoint URL (e.g., https://yourdomain.com/webhook/zapi).
     
     

   • Ensure the endpoint is HTTPS for security.
     
     

4. Test Webhook
   
   

   • Send a test message to your connected WhatsApp number.
     
     

   • Confirm that Z-API delivers the incoming message JSON to your webhook URL.
     
     

   • Log and inspect the payload structure (sender, message, timestamp, etc.).
     
     

5. Validate Security
   
   

   • Store your Instance ID and Security Token securely.
     
     

   • Configure authentication on your webhook endpoint (e.g., token validation).
     
     

6. Integrate with Automation Platform
   
   

   • If using n8n: create a Webhook node with your configured endpoint.
     
     

   • Parse the incoming JSON payload and route it to the appropriate flow.
     
     

   • Test full round-trip: User → WhatsApp → Z-API → Webhook → n8n → Response.
     
     

7. Monitoring & Maintenance
   
   

   • Regularly check Z-API dashboard for connection health.
     
     

   • Restart/re-link the WhatsApp instance if the session expires.
     
     

   • Keep logs of incoming webhook calls for debugging.

---

Documentation or References

• Z-API Official Documentation: https://z-api.io/docs

• Videoguide : https://docs.lowcode.agency/recordings/As8vGjDic6yDj0iYahB6