Webhooks

Receive real-time notifications when forms are submitted.

Webhook Payload

When a form is submitted, Trigglio sends a POST request to your webhook URL with the following payload:


{
  "eventType": "form_response",
  "eventId": "evt_unique_id",
  "createdAt": "2024-01-15T10:30:00Z",
  "data": {
    "formId": "frm_abc123",
    "formName": "Contact Form",
    "responseId": "resp_xyz789",
    "fields": [
      {
        "key": "name",
        "label": "Full Name",
        "type": "short_text",
        "value": "John Doe"
      },
      {
        "key": "email",
        "label": "Email Address",
        "type": "email",
        "value": "john@example.com"
      },
      {
        "key": "message",
        "label": "Your Message",
        "type": "long_text",
        "value": "I have a question about your service..."
      }
    ]
  },
  "metadata": {
    "source": "direct"  // "direct" | "embed" | "chatbot"
  }
}

Field Types

Type	Description
`short_text`	Single line text input
`long_text`	Multi-line textarea
`email`	Email address
`phone`	Phone number
`number`	Numeric input
`date`	Date picker
`dropdown`	Select dropdown
`multiple_choice`	Radio buttons
`checkboxes`	Multiple selection
`file`	File upload (returns URL)
`signature`	Signature (returns image URL)
`rating`	Star rating
`system`	System fields like `_formId`, `_responseId`

Handling Webhooks

Your webhook endpoint should:

Respond with a 200 status code to acknowledge receipt
Process the data asynchronously if needed
Handle retries gracefully (Trigglio may retry on failure)

Node.js (Express)


import express from 'express';
const app = express();
 
app.use(express.json());
 
app.post('/webhook', (req, res) => {
  const { eventType, data } = req.body;
 
  if (eventType === 'form_response') {
    console.log('New form submission!');
    console.log('Form:', data.formName);
    console.log('Response ID:', data.responseId);
 
    // Process each field
    for (const field of data.fields) {
      console.log(`${field.label}: ${field.value}`);
    }
  }
 
  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});
 
app.listen(3000, () => console.log('Webhook server running on port 3000'));

Knowledge Source Events

Subscribe to knowledge source lifecycle events to get notified when sources are created, processed, or deleted.

Event	Description
`knowledge.source.created`	A new knowledge source was created
`knowledge.source.ready`	A source finished processing and is searchable
`knowledge.source.error`	A source failed to process
`knowledge.source.deleted`	A source was deleted

Payload example (knowledge.source.ready):


{
  "eventType": "knowledge.source.ready",
  "eventId": "evt_abc123",
  "createdAt": "2024-06-15T10:35:00Z",
  "data": {
    "sourceId": "src_xyz789",
    "sourceName": "Product FAQ",
    "sourceType": "text",
    "chatbotId": "cm_abc123",
    "status": "ready",
    "chunkCount": 12
  }
}

Payload example (knowledge.source.error):


{
  "eventType": "knowledge.source.error",
  "eventId": "evt_def456",
  "createdAt": "2024-06-15T10:36:00Z",
  "data": {
    "sourceId": "src_xyz789",
    "sourceName": "Company Website",
    "sourceType": "url",
    "chatbotId": "cm_abc123",
    "status": "error",
    "error": "Failed to fetch URL: 404 Not Found"
  }
}

Testing Webhooks

Use the Get Sample Payload endpoint to get a sample payload for testing:


curl -X GET "https://trigglio.com/api/integrations/webhooks/triggers/sample?formId=frm_abc123" \
  -H "Authorization: Bearer tr_live_your_api_key"

For local development, use a tool like ngrok to expose your local server to the internet.

Retry Policy

If your webhook endpoint returns a non-2xx status code, Trigglio will retry the request:

3 retries with exponential backoff
Retries occur at approximately 1 minute, 5 minutes, and 30 minutes
After 3 failed attempts, the webhook is marked as failed

Make sure your endpoint is idempotent — use the eventId to detect duplicate deliveries.