Overview
A webhook is a callback over HTTP that you can configure to be notified about certain events in your Ambassador account. Using webhooks can open up many possibilities for more advanced integrations with Ambassador. For example, you can set up a webhook to hit your application whenever a contact is created and send them additional resources, add their information to your CRM, etc.
To receive a webhook, you will need a publicly accessible URL. When a given event occurs, such as creating a new contact, we will make a POST request to the URL of your choice with JSON data.
What types of webhooks can I set up?
Below is a list of available webhooks. For more information, such as response format, visit our Ambassador Developer Hub.
Contact Created: This event occurs whenever a contact is created.
Contact Added to Segment: This event occurs whenever a contact is added to one of your segments.
Contact Status Updated: This event occurs whenever a contact's status is changed (ex. contact is enrolled).
Contact Added to Campaign: This event occurs whenever a contact gains access to one of your campaigns.
Commission Created: This event occurs whenever a new commission is created.
Commission Status Updated: This event occurs whenever a commission status is changed e.g. commission is approved or denied.
Payout Created: This event occurs whenever a new payout is created.
Referral Created: This event occurs whenever a contact refers another contact.
Share Tracked: This event occurs whenever a share is tracked.
Click Tracked: This event occurs whenever a click is tracked.
How do I create a webhook?
You can create a webhook in just a few simple steps! Please note, only the main account admin can create and manage webhooks.
Step 1: In the navigation menu on the left, click "Settings."
Step 2: Next, click the “Notifications” tab. You'll be taken here.
Step 3: Once on this page, click the "Add notification" button to create your first webhook.
Step 4: A pop-up will launch to set up your notification, select the following.
Notify via: Select "Webhook."
How often: This is pre-selected to "Every Time."
When this happens: You can choose all events or a specific event from the list of webhooks above.
In campaign(s): Depending on the event selected above, you can choose all campaigns or a specific campaign.
Webhook URL: This is the endpoint where your data will be sent.
Enabled: Select "Yes" to turn the webhook on.
Step 5: Next, click the green "Add notification" button. Once added, a section called "Webhook Token" will appear. This secret token allows you to authenticate incoming webhooks.
Because you receive webhooks via a publicly accessible URL, it is important that you verify your webhooks are genuine. Learn more about webhook security here.
Step 6: Click "Save notification" to exit. To add additional webhooks, repeat the steps above.
