Receive a Webhook (Send a Payload to Leadfwd)

Add Contacts, Update Contact Data Field Properties, Tag Contacts and Enroll Contacts into Sequences with Webhooks.

Webhooks are a powerful and simple method to transmit useful data between applications when an 'event' occurs. While webhooks are similar to an API, they don't require scheduled polling to figure out when data is modified. Instead the webhook is triggered instantly when an event you define takes place.

• Why Use a Webhook Over an API?
• Authentication and Creating a Webhook Endpoint (URL)
• Rules: Create new, Update existing or Both
• Webhook Request
• Webhook Payload
• Enroll Contacts into Sequences and Add Tags with a Webhook
• Webhook Error Responses

Why Use a Webhook Over an API?

API’s require that we poll data frequently to get the data update we need. Polling is not an ideal solution for either the server or the client making the request. Ultimately it leads to a lot of wasted time and server resources to prepare and send requests and replying to responses that contains nothing new. Also, when there is data, it’s only as new as the latest polling interval, which means its not processed in real-time. 

The historic drawback to a webhook was that they could be complicated to set up. You would need to create a script called an end-point to receive your data or a custom script to gather and send data to another apps end-point. But, thanks to platforms like Zapier, a webhook can be easily created in a no-code setup wizard and connected thousands of apps in a matter of minutes.

Authentication and Creating a Webhook Endpoint

Leadfwd separates Webhooks into two categories, Inbound and Outbound. With an Inbound webhook we establish a unique URL endpoint for you to transmit and POST your data to and the endpoint is configured to write data to a specific Contact List within your Leadfwd account.

You will need your Authentication Key and Secret to successfully POST data to your webhook endpoint. Review these instructions to generate an Authentication Key and Secret.

Create Webhook Endpoint

1. Navigate to Settings

2. Expand Integrations and Select Webhooks

3. Click Inbound Connectors and Select Create Connector

4. Enter a Unique Name for your Webhook and Select the Contact database

5. Create new, Update existing or Both

You can specify whether or not your webhook should have access to Create new contacts, Update existing contacts or both.

Contact options...

• Create new only
• Update existing only
• Create new and update existing

Updating existing contacts can also be limited:

• Overwrite any existing data field values
• Only overwrite data fields with an empty value

Whether or not a contact is new or existing is determined based on their email address. If an email address already exists in your Contact database it will be considered existing and will follow the update rules you define. If your inbound connector is configured to create new contacts only, then if an email address already exists the process will end and not records will be created or updated.

Webhook Request

POST /v2/webhooks/$webhook_endpoint_string
HTTP/1.1
Authorization: Basic {$key}:{$secret}
Host: api.$leadfwd_domain
Accept: application/json
Content-Type: application/json

Webhook Payload

Each custom data field property within your selected destination list can be updated and written to by your webhook POST. 

{
  "email": "elon@tesla.co",
  "name": "Elon Musk",
  "Company": "Tesla",
  "title": "CEO"
}

Enroll Contacts in Sequences and Add Tags

Apply tags or enroll contacts into Sequences within a webhook post using parameters leadfwd_sequence_id and leadfwd_tags. You can locate the ID for a Sequence within the Sequence Manager. Multiple tags can be assigned by separating values by comma. 

{
  "email": "elon@tesla.co",
  "name": "Elon Musk",
  "Company": "Tesla",
  "title": "CEO"
  "leadfwd_sequence_id": "$id"
  "leadfwd_tags": "$tag1,$tag2,$tag3"
}

Success Response

HTTP/1.1 201 Created
{
    "id": "$id",
    "message": "Success!"
}

Error Responses

HTTP/1.1 401 Unauthorized
{
    "id": "0",
    "message": "Authentication failed. Your authentication info is invalid."
}

HTTP/1.1 405 Method Not Allowed
{
    "id": "0",
    "message": "The URL used in the API request is not valid"
}

HTTP/1.1 422 Unprocessable Entity
{
    "id": "0",
    "message": "Error description"
}