Learn how to use inbound webhooks to add contacts directly into your audience via a unique webhook URL.

What we'll cover

1. Concepts
2. How to configure an inbound webhook
3. How to regenerate an inbound webhook
4. How to delete an inbound webhook
5. FAQ
6. Troubleshooting
7. Need help?

1 Concepts

What are inbound webhooks?
Inbound webhooks let you add or update contacts in an audience automatically by posting JSON data or form data to a unique URL assigned to that audience. This is useful for integrating other platforms with Tarvent and avoiding manual imports.

Webhook behavior
You can use inbound webhooks in one of two ways:

• Add and update (upsert): Adds new contacts and updates existing contacts when a match is found.
• Add only: Adds new contacts only and returns an error if the contact already exists.

Real-time integration
Webhooks run the moment your external system sends a valid request—ideal for signup forms, CRMs, and other systems where you want contacts to appear immediately.

Double opt-in and inbound webhooks (SkipDoubleOptIn)
If your audience has double opt-in enabled, new contacts added by webhook normally enter the double opt-in flow and remain Pending until they confirm their subscription. If you want a webhook to add a contact as Active immediately (skipping double opt-in), include the SkipDoubleOptIn field in your request.

Note: Double opt-in is configured in Audience > Settings. Learn more about subscription confirmation settings here: Configure double opt-in.

2 How to configure an inbound webhook

Here are the steps:

1. Go to the audience where you'd like to receive incoming contacts.
2. Click Settings.
3. In the Inbound Webhook card, click Generate webhook URL.
4. Copy the Webhook URL provided. The first URL will add a contact or update an existing contact. The second URL will add a contact but return an error if the contact already exists.
   

   Warning: Copy the URL before you navigate away from this page. For security reasons, you won’t be able to view it again—you’ll need to regenerate it.

5. Send a POST request with a Content-Type: application/json or Content-Type: application/x-www-form-urlencoded header and body. Here is a JSON example:

   {
     "email": "janedoe@example.com",
     "firstName": "Jane",
     "lastName": "Doe",
     "tags": "tag1,tag2,tag3",
     "groupIds": "group_id_1,group_id_2",
     "SkipDoubleOptIn": false
   }

6. Make sure to include required fields as defined in your audience data fields.
7. Test your request to confirm the contact is added or updated successfully.

Pro-tip: Click View setup information in the Inbound Webhook card to see an example request body. We automatically include required fields to make setup easier.

3 How to regenerate an inbound webhook

Warning: Regenerating your webhook URL deletes your existing webhook URL. You’ll need to update any platforms or APIs that are using the old URL.

Here are the steps:

1. Go to the audience where you'd like to receive incoming contacts.
2. Click Settings.
3. In the Inbound Webhook card, click Regenerate.
4. Copy the Webhook URL provided.
   

   Note: The Regenerate option is only available after a webhook URL has been generated.

5. Follow the steps in How to configure an inbound webhook.

4 How to delete an inbound webhook

Here are the steps:

1. Go to the audience where you'd like to receive incoming contacts.
2. Click Settings.
3. In the Inbound Webhook card, click Delete.

5 FAQ

Can I change the update setting without regenerating the URL?
Yes. In the webhook URL, the number near the end determines the webhook mode: 1 means Add only (new contacts only), while 2 means Add and update (new or existing). You can switch between these modes by changing the number in the URL—no regeneration required.

How can I add a contact to a group using a webhook?
Use the groupIds property. The easiest way to get group IDs is to click View setup information and select the groups you want. Tags work the same way using the tags property.

How does SkipDoubleOptIn work?
SkipDoubleOptIn is an optional Boolean field that controls whether a contact should skip double opt-in when added by webhook.

• When SkipDoubleOptIn is true: The contact is added with a status of Active, skipping the double opt-in process configured in Audience > Settings.
• When SkipDoubleOptIn is false or not provided: If double opt-in is enabled for the audience, the contact will go through the double opt-in flow and remain Pending until they confirm their subscription. If double opt-in is not enabled, the contact is added normally.

Note: This field is parsed as a Boolean by Tarvent. You can provide true/false or 1/0 as the value.

6 Troubleshooting

Common issues:

• Missing required fields in the request body
• Incorrect Content-Type header
• Invalid JSON structure or typos in field names

7 Need help?

If you need assistance with setup or formatting, contact support. We’re happy to help!