Generic webhooks allow you to send contact data to a URL of your choosing in JSON format via a POST request.
To view or test the data sent by our webhooks, we recommend you use a site like webhook.site.
Note: Webhooks does not offer automatic suppression. You will need to set up an integration via API or manually upload your suppression file. (See Suppress Contacts below.)
How to set up Generic Webhooks
1. Go to your Retention dashboard and select Integrations from the navigation menu.
Click Available Integrations at the top and choose the Webhook icon.
2. Type your test URL into Webhook URL field.
You can also enter custom JSON data in the box below it. This will be merged with the contact data we pass through to the webhook endpoint.
If you get an error with credentials here, that error is coming from your URL's server.
3. Once you've filled out the appropriate fields click the connect button. You will see a success confirmation on the top right hand of your screen. When the integration is connected, we will automatically send a sample test event.
4. Click Yes to upload collected contacts. Then, click Next.
5. Enable the integration, and click Finish.
6. You will be taken to the Integration Settings page. Here you can view your API Details, Disable/Enable or Remove the integration, and turn Contact Sync on/off.
What will the data look like?
We provide two distinct webhook integration options: "Grow" and "Reclaim."
Below, you will find examples illustrating the format and structure of the data that will be transmitted to your designated webhook URL:
Grow Webhook data
{
"email": "test@retention.com",
"email_domain": "@retention.com",
"first_name": "First Name",
"last_name": "Last Name",
"address_line_1": "Address",
"address_city": "City",
"address_state": "State",
"address_postal": "Zip",
"clicked_at": "Mon, 28 Nov 2022 19:47:42 UTC +00:00",
"landing_page_url": "https://yourwebsite.com",
"landing_page_domain": "yourwebsite.com",
"referrer": "https://some.referralurl.com",
"page_title": "Page Title Here"
}
Reclaim Webhook data (Add to cart)
{
"email": "test@retention.com",
"event_type": "Add To Cart Reclaim",
"occurred_at": "2024-02-08T21:39:06Z",
"properties": {
"product_url": "https://www.retention.com",
"product_name": "Test Product",
"product_id": "123456",
"product_image_url": "https://images.retention.com/assets/logo-full-page.png",
"product_price": "10.00",
"quantity": "1"
}
}Note: If you are on an email-only plan, you will not receive first name, last name, or address data.
Send a test event
Automatic Test Event: When you Connect the webhook, we will send a test event with an email address. We do not include all fields in the test; the test hook is a generic event to validate header/body type/etc.
Additional Test Events: To send additional test events, simply Disable/Enable your webhook integration, or open the integration settings and save/exit. Any edit action in your webhook will trigger an additional test event.
Suppress contacts
To prevent collecting contacts you already have, you will need to setup automatic suppression via API or manually suppress them by uploading a CSV file.
Suppression via API
You can set up daily suppression via our API. Find more information on that here.
Manual suppression
Suppression lists loaded as a CSV file are converted into encoded MD5s for security reasons. We do not use, share, or resell this data for any purpose other than to prevent users from collecting and paying for contacts they already have.
To upload a Suppression List, click on Suppression Lists in the left-hand navigation.
Here are the file requirements for upload:
Your file should only contain ONE column, labeled “email”.
You’ll also need to save it as an Excel .CSV file.
Maximum file size is 100MB. If your file is larger than this, split it up into several smaller files.
Once the file has uploaded, you will see a green box in the top-right corner that says your file has been uploaded and is in the queue to be processed. Once that’s complete, you’ll see the stored file listed under the corresponding date:
After you upload the initial file, you will need to continue uploading a CSV file to suppress contacts. How often you need to upload a CSV suppression list (ex. daily, weekly, bi-weekly, monthly) will depend on how many contacts you collect in your ESP.