Webhooks

Use Basin to repost submission data to other apps and services.

Configuring a webhook

If you only need to forward submission data to a single app or service, then a custom webhook is a great solution. Basin supports the following types of payloads for custom webhooks:

1. JSON
2. Data wrapped JSON
3. Form URL encoded
4. Customer.IO
5. Microsoft Teams
6. MailerLite
7. Pardot Form Handler
8. Custom Webhook Template

To setup a custom webhook in Basin, go to the Integrations page in your form dashboard, enter your desired URL in the input field, save, and you're all set!

When a submission is received by an endpoint with a configured webhook URL, Basin will queue up a post on your behalf. If the webhook fails, we will retry up to 15 times over the course of 24-28 hours with an exponential backoff. The format of our webhooks will be exactly what we receive on the inital form submission.

Webhook Triggering

Only submissions that are not flagged as spam will trigger a webhook by default. There is a checkbox to enable webhooks for all submsissions. This is an excellent strategy for bypassing any spam filtering by Basin.

Payload Types

JSON

{
  "email": "example@example.com",
  "name": "Example Name",
  "id": "submission_id",
  "attachments": [
    {
      "attachment_proxy_url": "proxy_url",
      "public_url": "public_url"
    }
  ]
}

Data wrapped JSON

{
  "data": {
    "email": "example@example.com",
    "name": "Example Name",
    "id": "submission_id",
    "attachments": [
      {
        "attachment_proxy_url": "proxy_url",
        "public_url": "public_url"
      }
    ]
  }
}

Customer.IO

{
  "data": {
    "email": "example@example.com",
    "name": "Example Name",
    "submission_id": "submission_id"
  }
}

Form URL encoded/Pardot Form Handler

For Form URL encoded and the Pardot Form Handler, the form data is sent as is without any additional processing. Here is an example:

{
  "data": "email=example@example.com&name=Example+Name&id=submission_id"
}

The only difference between the Form URL encoded and the Pardot Form Handler is when the submission has array values. Pardot Form Handlers do not support array values and require duplicate keys for each array value.  The Pardot Form Handler payload type will properly send array values using multiple duplicate keys.

MailerLite integration

The MailerLite payload type will send the submission data to MailerLite as follows:

{
  "email": "example@example.com",
  "fields": {
    "name": "Example Name",
    "id": "submission_id"
  }
}

Customer.IO integration

To integrate your form with Customer.io using webhooks, follow these steps:

1. Open your Basin dashboard and navigate to the form you wish to integrate with Customer.io.
2. Go to 'Integrations' and then 'Webhooks'.
3. Click on 'Create a new webhook'.
4. In the 'Webhook URL' field, enter the webhook URL provided by Customer.io for your form.
5. In the 'Payload Format' field, select "Customer IO."
6. Provide the necessary authentication headers. Use "Authorization" as the Header Name and "Basic YOUR_CUSTOMER_IO_API_KEY" as the Header Value, replacing YOUR_CUSTOMER_IO_API_KEY with your actual Customer.io API key.

With these steps, your form is now integrated with Customer.io and will send data via webhooks.

Microsoft Teams Integration

Seamlessly send submission data to your Microsoft Teams channels with our Basin-Teams integration. Head to our Microsoft Teams integration guide to get started.

Pardot Form Handler Integration

To integrate your form with Pardot using webhooks, follow these steps:

1. Open your Basin dashboard and navigate to the form you wish to integrate with Pardot.
2. Go to 'Integrations' and then 'Webhooks'.
3. Click on 'Create a new webhook'.
4. In the 'Webhook URL' field, enter the webhook URL provided by your Pardot form handler.
5. In the 'Payload Format' field, select "Pardot."
6. Provide any necessary authentication headers.

With these steps, your form is now integrated with Pardot and will send data via webhooks.

Custom Webhook Template

If our pre-built payloads do not meet your requirements, you can create a custom webhook using our flexible template builder.  This allows seamless integration with any API, providing you with the ultimate customization and control over your form submissions.

Setup a custom webhook template

1. Open your Basin dashboard and navigate to the form you wish to integrate with a custom webhook body.
2. Go to 'Integrations' and then 'Webhooks'.
3. Click on 'Create a new webhook'.
4. In the 'Webhook URL' field, enter the webhook URL you wish to send the payload to.
5. In the 'Payload Format' field, select "Custom."
6. Provide any necessary authentication headers.
7. Save the webhook.
8. Edit the webhook body by following the link to 'Edit Custom Format'

Webhook templates support merge tags, placeholders for submission data that are dynamically replaced with the submission data when the webhook is sent. To learn more about merge tags, check out our docs here.

Custom Webhook Content Types

Basin supports several different content types for sending webhook data:

• application/json
• application/xml
• application/x-www-form-urlencoded
• multipart/form-data
• text/plain
• application/graphql

n8n Integration Example

Here's a complete example of setting up a custom webhook body for n8n integration using the application/json content type.

Standard JSON vs Custom Template

For basic n8n integrations, you can simply use the standard "JSON" payload format from the dropdown, which will send all form data in a clean JSON structure. Use the custom template below when you need additional data like source tracking, lead scoring, or custom formatting for your n8n workflow.

Setup Steps

1. Open your Basin dashboard and navigate to the form you wish to integrate with n8n.
2. Go to 'Integrations' and then 'Webhooks'.
3. Click on 'Create a new webhook'.
4. In the 'Webhook URL' field, enter your n8n webhook URL.
5. In the 'Payload Format' field, select "Custom."
6. Set the content type to "application/json".
7. Save the webhook.
8. Edit the webhook body by following the link to 'Edit Custom Format'

Example Custom Template for n8n

Use this sample template in the custom webhook body editor:

{
  "form-name": "{{form_name}}",
  {{#each form_params}}
    "{{this.name}}": "{{JSONstringify this.value}}",
  {{/each}}
  {{#if source_url}}
    "source_host": "{{source_host}}",
    "source_path": "{{source_path}}",
    "source_query": {
      {{#if source_query}}
        {{#each source_query}}
          "{{this.name}}": "{{this.value}}"{{#unless @last}},{{/unless}}
        {{/each}}
      {{/if}}
    },
    "source_fragment": "{{source_fragment}}",
  {{/if}}
  {{#if lead_agent.score}}
    "lead_agent": {
      "score": "{{lead_agent.score}}",
      "score_reasoning": "{{lead_agent.score_reasoning}}",
      "score_location_info": "{{lead_agent.score_location_info}}"
    },
  {{/if}}
  "attachments": [
    {{#each attachment}}
      {
        "name": "{{this.name}}",
        "public_url": "{{this.public_url}}",
        "file_size": "{{this.file_size}}"
      }{{#unless @last}},{{/unless}}
    {{/each}}
  ]
}

Using JSONstringify Helper

The JSONstringify helper in the form_params loop ensures that form field values are properly escaped for JSON. This is especially important when form data contains special characters, quotes, or line breaks that could break the JSON structure. Without this helper, a form submission with a value like He said "Hello" could create invalid JSON.

This template provides a comprehensive payload that includes:

• Form identification: The name of the form that submitted the data
• Form data: All form field values with proper JSON escaping
• Source tracking: Information about where the form was submitted from (URL, host, path, query parameters, and fragment)
• Lead scoring: If enabled, includes lead agent scoring data and reasoning
• File attachments: Details about any uploaded files including names, URLs, and file sizes