Webhooks — Incoming Triggers & Lead Capture

XSender exposes inbound HTTP webhooks so that any external system can push data into a workflow — your storefront, CRM, billing system, IoT device, Zapier, Make, or a custom backend. This is the primary way to "process incoming messages and events" inside XSender.

There is one canonical inbound endpoint and several specialised ones. Each is documented below with the request shape, what XSender does on receipt, and a copy-pasteable example.

When to use a webhook vs the Send API

You want to…	Use
Send a single transactional message	Send API (`/api/{channel}/send`)
React to an event in your system (signup, order, support reply) by enrolling a contact into a workflow	Automation Trigger Webhook
Receive delivery events from your ESP (Mailgun open, SES bounce, …)	Email Delivery Webhooks
Capture leads submitted on Meta / Google ad forms	Lead Capture Webhooks
Sync session state between the WhatsApp Node service and the app	WhatsApp Session Webhook

Automation Trigger Webhook — `POST /api/automation/webhook/{id}`

This is the most powerful inbound endpoint. It lets any external system trigger an automation workflow in XSender by POSTing a JSON payload that identifies a contact (email, phone, or WhatsApp number) plus any custom fields you want available inside the workflow.

Step 1 — Create a Webhook trigger node in the workflow

In Automation → Workflows → New Workflow, drag the Webhook trigger onto the canvas. XSender generates a unique webhook_id for that node — copy the full URL.

Step 2 — POST to the webhook URL

curl -X POST https://YOUR-XSENDER-DOMAIN/api/automation/webhook/4f2c1b8d-9e6a-4f0b-bcde-1234567890ab \
  -H "Content-Type: application/json" \
  -d '{
    "email":      "[email protected]",
    "phone":      "+15555550123",
    "first_name": "John",
    "last_name":  "Doe",
    "order_id":   "A1023",
    "amount":     "129.95"
  }'

What happens on receipt

XSender resolves the contact: existing contact with that email/phone is reused; otherwise a new contact is created.
All keys in the payload are written as contact attributes, so subsequent workflow nodes can reference them with {{ order_id }}, {{ amount }}, etc.
The contact is enrolled into every workflow whose Webhook trigger matches this webhook_id.
The workflow runs (send email, send SMS, branch on conditions, wait, call another webhook, …).

Response

{
  "success": true,
  "message": "Webhook processed",
  "workflows_triggered": 2,
  "contacts_enrolled":   1
}

Common integrations

Zapier / Make: add a "Webhooks → POST" step pointing at the URL.
Stripe / Paddle / Razorpay: add this URL as a webhook receiver and the order details flow straight into a "Payment Received" workflow.
WordPress / WooCommerce: use any "send webhook on event" plugin to fire on new order, new comment, etc.
Custom backend: any language with HTTP support can POST here.

Authentication: the unguessable webhook_id in the URL acts as the secret. Treat it like an API key. Rotate it (delete + recreate the trigger node) if you suspect leakage.

Lead Capture Webhooks

Meta Lead Ads — `POST /api/webhook/meta-lead-ads`

Configured automatically when you connect a Meta page in Lead → Lead Generation → Meta. XSender:

Verifies the subscription with Meta's hub.challenge handshake on GET.
Receives leadgen events on POST, retrieves the lead details from the Graph API, maps fields, creates or updates a contact, and (optionally) enrols it into a workflow.

Google Ads Lead Form — `POST /api/webhook/google-ads-lead`

Set this URL inside the Google Ads Lead Form Extension. XSender validates the Google-signed payload, maps fields, and creates contacts the same way.

Both endpoints are exempt from rate-limiting.

WhatsApp Session Webhooks

These are used internally by the bundled WhatsApp Node service (whatsapp-node-service) to keep the XSender database in sync with the live WhatsApp Web sessions. You normally don't call them directly, but they are documented here for self-hosted users who run their own node service.

Method	Path	Purpose
POST	`/api/whatsapp/session/status`	Push session state changes (connected / disconnected / qr).
POST	`/api/whatsapp/session/sync`	On node startup, bulk-sync all sessions.
GET	`/api/whatsapp/session/status/{sessionId}`	Read the latest session status.
POST	`/api/whatsapp/node/webhook`	Inbound message + status events from the node service.

Testing webhooks

Use a tool such as curl, Postman, or webhook.site as a transparent proxy.
From XSender, open the workflow and check the Workflow Executions tab — every webhook fire is logged with timestamp, payload, and the contact enrolment outcome.
For Meta / Google, the platform console shows delivery attempts and any 4xx/5xx XSender returned.

Security checklist

Webhook URLs contain unguessable IDs — keep them out of public client-side code.
Always serve XSender over HTTPS.
If your ad-platform requires payload signing (Meta, SES SNS), XSender verifies the signature automatically; do not disable verification.
Webhook endpoints bypass the standard throttle:api middleware but are still protected by Laravel's CSRF exemption + content-type checks.