Webhook Events

Reference for the AlonChat webhook event types you can subscribe to and what they signal.

Webhook Events#

AlonChat sends real-time HTTP POST notifications when key events happen in your agent. Subscribe to the events you care about when you create a webhook under Settings > Webhooks.

Tip: Use the Test button on any webhook in the dashboard to see the exact payload for a given event before you build against it. Test payloads include a flag so you can tell them apart from real events.

Supported Events#

Event	Fires when
`leads.submit`	A customer submits lead/contact details in a conversation
`message.sent`	The AI sends a message to a customer
`tool.executed`	An AI action/tool call completes successfully
`booking.created`	A booking/appointment is created
`booking.cancelled`	A booking is cancelled
`booking.rescheduled`	A booking is moved to a new time
`order.confirmed`	A customer confirms an order
`custom_form.submitted`	A custom form is submitted
`payment.proof_received`	A customer submits proof of payment
`payment.verification_pending`	A payment is awaiting your approval
`payment.verified`	A payment is approved/verified
`payment.rejected`	A payment is rejected

action.executed is accepted as a legacy alias for tool.executed.

These map cleanly onto AlonChat's Automations — bookings, orders, payments, custom forms, and lead capture — so you can drive your own systems (CRM, accounting, fulfillment) off the work your agent does.

Payloads#

Every delivery uses a standard envelope: eventType, chatbotId (the agent ID), a payload with the event-specific data, and a timestamp. The HMAC signature is computed over this entire JSON body. The simplest example is a lead:

json

{
  "eventType": "leads.submit",
  "chatbotId": "agent-uuid",
  "timestamp": "2026-03-15T10:30:00Z",
  "payload": {
    "conversationId": "conv-uuid",
    "customerEmail": "john@example.com",
    "customerName": "John Doe",
    "customerPhone": "+639171234567"
  }
}

custom_form.submitted#

The custom form event carries the submission, the resolved field values (by key and by label), and the form's field schema:

json

{
  "eventType": "custom_form.submitted",
  "chatbotId": "agent_123",
  "timestamp": "2026-05-28T10:30:00Z",
  "payload": {
    "formId": "form_123",
    "formKey": "refund_request",
    "formName": "Refund Request",
    "submissionId": "sub_123",
    "activityCaseId": "case_123",
    "conversationId": "conv_123",
    "contactId": "contact_123",
    "customerName": "Juan Dela Cruz",
    "customerEmail": "juan@example.com",
    "customerPhone": "09171234567",
    "sourcePlatform": "facebook",
    "fieldValues": { "order_reference": "REF-123", "reason": "Duplicate payment" },
    "fieldValuesByLabel": { "Order Reference": "REF-123", "Reason": "Duplicate payment" },
    "fieldSchema": [
      { "key": "order_reference", "label": "Order Reference", "type": "text", "required": true },
      { "key": "reason", "label": "Reason", "type": "textarea", "required": true }
    ],
    "notes": null,
    "submittedAt": "2026-05-28T10:30:00Z"
  }
}

Payload shapes vary by event — booking, order, and payment events carry the relevant record details. Use the dashboard Test button to inspect the exact fields for the event you're building against.

Common Fields#

Field	Type	Description
`eventType`	string	Event identifier (e.g., `leads.submit`)
`chatbotId`	UUID	The agent that triggered the event
`payload`	object	Event-specific data (varies by event)
`timestamp`	ISO 8601	When the event occurred (UTC)

Timestamps use ISO 8601 with UTC, e.g. 2026-03-15T10:30:00Z.

Event Filtering#

When creating a webhook, choose which events to receive:

From the dashboard: go to Settings > Webhooks, click Add Webhook, and check the events you want.

Via the API:

json

{
  "name": "Order Notifications",
  "endpoint_url": "https://your-server.com/webhooks/alonchat",
  "events": ["order.confirmed", "payment.verified", "custom_form.submitted"]
}

Subscribe only to the events you need to reduce traffic and processing overhead.

Event Delivery#

At-Least-Once Delivery#

AlonChat uses at-least-once delivery. Events are guaranteed to arrive at least once but may be delivered more than once during retries. Use the x-alonchat-delivery-id header to deduplicate.

javascript

const processedDeliveries = new Set()

app.post('/webhooks/alonchat', (req, res) => {
  const deliveryId = req.headers['x-alonchat-delivery-id']
  if (processedDeliveries.has(deliveryId)) {
    return res.status(200).json({ success: true, duplicate: true })
  }
  // Process event...
  processedDeliveries.add(deliveryId)
  res.status(200).json({ success: true })
})

For production, store delivery IDs in a database or Redis instead of an in-memory set.

Delivery Order#

Events arrive roughly in chronological order, but strict ordering isn't guaranteed. Use the timestamp to order events when it matters.

Next Steps#

Webhook Security — verify signatures
Webhook Examples — integration recipes
Webhooks Overview — setup and configuration