Skip to main content

Webhooks

Endatix provides a flexible webhook system that allows you to send notifications to external systems when specific events occur. This guide will show you how to configure webhooks at different levels.

Overview​

Webhooks in Endatix are built-in event handlers that automatically send HTTP requests to configured endpoints when specific events occur. The system supports the following events:

  • Form events (FormCreated, FormUpdated, FormEnabledStateChanged, FormDeleted)
  • Submission events (SubmissionCompleted)

Configuration Levels​

Webhooks can be configured at two levels:

  1. Tenant level - Default webhook settings that apply to all forms within a tenant
  2. Form level - Specific settings for individual forms that override the tenant settings
Important

Form-level webhook settings completely override tenant-level settings. When a form has its own webhook configuration, the tenant-level settings are ignored for that form.

Webhook Settings Format​

Both tenant and form webhook configurations use the same JSON format:

{
  "Events": {
    "FormCreated": {
      "IsEnabled": true,
      "WebHookEndpoints": [
        {
          "Url": "https://your-endpoint.com/webhook",
          "Authentication": {
            "Type": "None"
          }
        }
      ]
    },
    "SubmissionCompleted": {
      "IsEnabled": true,
      "WebHookEndpoints": [
        {
          "Url": "https://your-endpoint.com/webhook",
          "Authentication": {
            "Type": "ApiKey",
            "ApiKeyHeader": "X-API-KEY",
            "ApiKey": "your-secret-key"
          }
        }
      ]
    }
  }
}
tip

This example shows configuration for FormCreated and SubmissionCompleted events. The other supported events (FormUpdated, FormEnabledStateChanged, FormDeleted) are configured the same way.

Tenant-Level Configuration​

Tenant webhook settings are stored in the TenantSettings table in the WebHookSettingsJson column. These settings serve as the default webhook configuration for all forms belonging to the tenant.

note

Currently, tenant webhook settings must be configured directly in the database. An API endpoint for managing tenant settings is expected in a future release.

Form-Level Configuration​

Form webhook settings can be configured via the Forms API endpoints. The webHookSettingsJson field accepts the same JSON format as tenant settings.

API Endpoints​

  • POST /api/forms - Create a new form with webhook settings
  • PUT /api/forms/{formId} - Update a form (full update) with webhook settings
  • PATCH /api/forms/{formId} - Partially update a form with webhook settings

Important Notes on the webHookSettingsJson Field​

  • The field is optional - omit it entirely to use tenant-level settings
  • To remove form-level overrides and fall back to tenant settings, do not include the field in your request
  • Providing an empty object "{}" will override the settings with an empty configuration (no webhooks will fire for this form)

Example: Creating a Form with Webhooks​

curl -X POST https://your-api.com/api/forms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "name": "Contact Form",
    "isEnabled": true,
    "webHookSettingsJson": "{\"Events\":{\"SubmissionCompleted\":{\"IsEnabled\":true,\"WebHookEndpoints\":[{\"Url\":\"https://your-endpoint.com/webhook\",\"Authentication\":{\"Type\":\"None\"}}]}}}"
  }'

Example: Updating Form Webhooks​

curl -X PATCH https://your-api.com/api/forms/{formId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "webHookSettingsJson": "{\"Events\":{\"SubmissionCompleted\":{\"IsEnabled\":true,\"WebHookEndpoints\":[{\"Url\":\"https://new-endpoint.com/webhook\",\"Authentication\":{\"Type\":\"None\"}}]}}}"
  }'

Webhook Authentication​

Endatix supports configurable authentication for securing your webhook endpoints. You can configure authentication per endpoint to match your API requirements.

Authentication Types​

1. API Key Authentication (ApiKey)​

Sends an API key in a custom header:

{
  "Url": "https://api.example.com/webhooks",
  "Authentication": {
    "Type": "ApiKey",
    "ApiKeyHeader": "X-SURVEY-API-KEY",
    "ApiKey": "your-secret-api-key"
  }
}

2. No Authentication (None)​

No authentication headers are sent:

{
  "Url": "https://api.example.com/webhooks",
  "Authentication": {
    "Type": "None"
  }
}

Testing Webhooks​

You can use webhook.site to test your webhook implementation. This service provides a unique URL that you can use as your webhook endpoint. It will display all incoming requests in real-time, allowing you to:

  • View the complete request payload
  • Inspect headers
  • See the exact format of the data being sent
  • Test different event types
  • Verify the webhook message structure

To test your webhooks:

  1. Go to webhook.site
  2. Copy the unique URL provided
  3. Configure this URL as your webhook endpoint (either at tenant or form level)
  4. Trigger events in your application
  5. View the incoming webhook requests on webhook.site

Example Test Configuration​

{
  "Events": {
    "FormCreated": {
      "IsEnabled": true,
      "WebHookEndpoints": [
        {
          "Url": "https://webhook.site/your-unique-id",
          "Authentication": {
            "Type": "None"
          }
        }
      ]
    },
    "FormUpdated": {
      "IsEnabled": true,
      "WebHookEndpoints": [
        {
          "Url": "https://webhook.site/your-unique-id",
          "Authentication": {
            "Type": "None"
          }
        }
      ]
    },
    "SubmissionCompleted": {
      "IsEnabled": true,
      "WebHookEndpoints": [
        {
          "Url": "https://webhook.site/your-unique-id",
          "Authentication": {
            "Type": "None"
          }
        }
      ]
    }
  }
}

Available Events​

Form Events​

  • FormCreated: Triggered when a new form is created

    • Endpoints that can trigger the event:
      • POST api/forms
    • Useful for synchronizing form data with external systems or triggering notifications

  • FormUpdated: Triggered when a form is updated

    • Endpoints that can trigger the event:
      • PUT api/forms/{formId}
      • PATCH api/forms/{formId}
    • This event is triggered when performing form update action even if all the data remains the same
    • Can be used to track form changes and update related systems

  • FormEnabledStateChanged: Triggered when a form's enabled state changes

    • Endpoints that can trigger the event:
      • PUT api/forms/{formId}
      • PATCH api/forms/{formId}
    • This event is triggered only when the value of IsEnabled field changes
    • Useful for managing form availability in external systems

  • FormDeleted: Triggered when a form is deleted

    • Endpoints that can trigger the event:
      • DELETE api/forms/{formId}
    • This event is triggered when a form is soft-deleted
    • Useful for cleaning up related data in external systems or triggering notifications

Submission Events​

  • SubmissionCompleted: Triggered when a form submission is completed
    • Endpoints that can trigger the event:
      • POST api/forms/{formId}/submissions
      • PUT api/forms/{formId}/submissions/{submissionId}
      • PATCH api/forms/{formId}/submissions/{submissionId}
      • PATCH api/forms/{formId}/submissions/by-token/{submissionToken}
    • This event is triggered once per submission when IsComplete field is set to true
    • Can be used to process form responses, trigger workflows, or update external systems

Webhook Message Structure​

Each webhook message contains:

  • Id: Unique Snowflake-generated webhook message id
  • EventName: The type of event (e.g., form_created, form_updated, form_enabled_state_changed, form_deleted, submission_completed)
  • Action: The action that triggered the event (e.g., created, updated, deleted)
  • Payload: The event data specific to the operation, containing the complete entity data. It includes explicit entity identifier fields, such as formId for form events and submissionId for submission events

Best Practices​

  1. Error Handling: Design your webhook receiving endpoints to handle errors gracefully
  2. Logging: Log incoming webhook requests for debugging and auditing
  3. Idempotency: Design your webhook handlers to be idempotent to handle potential duplicate deliveries
  4. Validation: Validate the payload structure and required fields before processing
  5. Use Form-Level Sparingly: Only configure form-level webhooks when you need different behavior than the tenant default