A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both provider and consumer.

Webhook Name	Your reference, just name it something obvious and easy to remember.
URL	Enter the endpoint URL you were given from your API
Payload Includes	Select the information you wish to include in the webhook payload e.g. Lead Message: e.g accepted/rejected Lead Costs: the lead costings Lead Revenue: the lead revenue Lead Data: all field data within the campaign
Lead Status Triggers	You can specify to only trigger if a lead reaches a certain status e.g. Received, Accepted, Flagged, Rejected, Pending, Client Rejected, Quarantine, Sale
Campaign Triggers	Choose to only trigger based a specific campaign /campaigns
Supplier Triggers	Choose to only trigger based a specific supplier/suppliers

Lead status webhooks

Databowl can send a HTTP request to your webhook URL whenever a lead's status has changed. You can also configure the webhooks to only send on specific lead statuses, specific campaigns, or specific suppliers.

Request payload

The following is a sample request:

Databowl-Timestamp: 1565534757Databowl-Signature-V1:2c06eeea54604794df1a36c739042fc6a143f5252f5a09ff6fa04aa8f7b03e9bDatabowl-Webhook: 2Databowl-Instance: your-databowl-instanceContent-Type: application/json{"event": "lead_update","payload": {"leadId": 13821420,"campaignId": 1376,"supplierId": 274,"previousStatusId": 4,"statusId": 1,"receivedAt": 1565772370,"instance": "your-databowl-instance","normalCost": 42,"previousNormalCost": 0,"normalRevenue": 34,"previousNormalRevenue": 0,"data": {"1": "lead@email.com","3": "+447777777777","7": "George","9": "Arthur","14": "Mr","29": "15 Abbey Road"},"optinData": [],"message": ""}}

The cost, revenue, message, and lead data fields are optional and can be removed in the webhook settings.

Webhook and Lead Data

The webhook data is sent in a JSON format, If the lead data is being passed, you'll see this come through as a variable called data in the JSON.

The Data variable is an object that contains all the lead data that is being passed.

Each field is stored in the object with a key that matches the field id.

These field ID's match the F_ number that is referenced in your integration document for the campaigns.

Message Verification

You can verify that HTTP requests your URL receives is from Databowl using the Databowl-Signature-V1 header and the webhook secret (this is generated for you when the webhook is created in Databowl).

The signature is the SHA256 HMAC value of the following value, using the webhook secret as the key:

<Databowl-Timestamp Header Value>.<Request Body>

You can verify that HTTP requests your URL receives is from Databowl using the Databowl-Signature-V1 header and the webhook secret (this is generated for you when the webhook is created in Databowl).

The signature is the SHA256 HMAC value of the following value, using the webhook secret as the key:

<Databowl-Timestamp Header Value>.<Request Body>

Understanding webhook data

When you receive a webhook, you'll receive a JSON with all your data.

Here's a breakdown of what this means

leadId

The ID of your lead, you can use this to find it easily in databowl

campaignId

This is the ID for your campaign.

supplierId

ID of your supplier

statusId

This is the current status of the lead. The following table maps the status identifiers to human readable status names:

Status ID	Name	Description
1	Received	The lead has been conditionally accepted pending response from client.
2	Rejected	The lead has been rejected.
3	Flagged	There are one or more potential problems with the lead. This is only a temporary status while the lead is either automatically or manually reviewed.
4	Pending	The lead has been received and is queued for further checks. This status is only temporary.
5	Quarantine	The lead is not currently accepted due a cap being reached. However, the lead may be accepted at a later date. Not applicable to all campaigns
6	Accepted	The lead has been accepted. Note, this may be conditionally.
7	Client Rejected	The lead has been rejected by the client.
8	Sale	The lead has been marked as a sale.