Webhooks

Webhooks notify your application in real-time when events occur on your WhatsApp account or connected store. Set your destination webhook URL inside your dashboard Settings page to start listening.

Shopify Webhook Events

When a Shopify store is connected, Whatapi automatically registers the following webhooks:

TopicTriggerTemplate Key
orders/createA new order is placedorder_confirmed
orders/paidPayment is received for an orderpayment_received
fulfillments/createAn order is fulfilled/shippedorder_shipped
orders/cancelledAn order is cancelledorder_cancelled
refunds/createA refund is processedrefund_processed

Webhook Processing Flow

  1. Shopify sends a `POST` request to `/api/shopify/webhook` with the event payload
  2. Whatapi resolves the user and store from the request
  3. If automations are **paused**, the webhook is acknowledged but skipped
  4. The system loads the user's custom message template (or falls back to defaults)
  5. All template placeholders are replaced with actual order data
  6. The WhatsApp message is sent via the user's connected session
  7. The delivery is logged in Firestore's `messages` collection

Template Placeholders

These placeholders are automatically replaced in your message templates:

PlaceholderDescription
{customerName}Customer's full name
{customer_name}Customer's full name (alias)
{customer_email}Customer's email address
{customer_phone}Customer's phone number
{orderId}Order ID
{order_number}Order number
{order_date}Order date
{totalPrice}Total order price
{order_total}Total order price (alias)
{currency}Currency code (e.g. USD, PKR)
{payment_method}Payment method used
{order_status}Order status
{items_list}Formatted list of ordered items
{items_count}Number of items in the order
{shipping_address}Shipping address
{shipping_city}Shipping city
{trackingNumber}Tracking number
{tracking_number}Tracking number (alias)
{trackingUrl}Tracking URL
{tracking_url}Tracking URL (alias)
{store_name}Store name
{store_url}Store URL

Customizing Templates

You can customize WhatsApp notification templates from your dashboard's **Message Templates** page. Templates are stored per-user in Firestore and support all the placeholders listed above.

Example Template

Hello {customerName}! ✅

Your order #{orderId} has been confirmed!
Total: {currency} {totalPrice}
Items: {items_list}

We'll notify you when it ships.

Thank you for shopping at {store_name}! 🎉

Best Practices

  • Test your templates using the template tester endpoint before going live
  • Set reasonable delays between bulk messages to avoid being rate-limited by WhatsApp
  • Monitor your webhook logs in the dashboard to catch delivery failures
  • Use meaningful template names to keep organized across multiple stores