API Webhook Subscriptions
About Webhook Subscriptions
Applies to: ONTRAPORT Pro and above for all objects. ONTRAPORT Basic and Plus can subscribe to Contacts webhooks.
ONTRAPORT exposes several endpoints for webhook subscriptions. When a subscribed event happens ONTRAPORT will send a data payload to the subscribed URL. This eliminates frequent polling requests checking for new information by the developer's application and reduces traffic on both the developer's server and ONTRAPORT's API servers.
Webhook Subscriptions
The API doc has the list of webhook subscriptions available:
- Object is created (Contact or Custom Object record)
- Form is submitted
- Tag is added
- Tag is removed
Webhook Subscription Requirements
The application will need to subscribe to the API endpoint with a valid API Key and Application ID from the ONTRAPORT account. The subscription request must provide a valid URL that will receive and process the data payload in the webhook.
Webhook Subscription Data Payload Format
A webhook for "Tag is added" looking for "tag_id 4" added to any contact would send a data payload like this:
webhook_id=3 object_type_id=0 event[type]=sub_tag event[tag_id]=4 data[id]=8 data[firstname]=Mary data[lastname]=Smith data[email]=mary@ontraport.com timestamp=1514940140
Three data formats are available for the data payload. The default is to return all information available about the record. In addition, developers can specify the following formats:
Notify: This format is a simple notification that returns the record ID number for future processing. This is useful for records that autosave such as manual entry of Contact Records. During manual entry of a new Contact Record the autosave activates as soon as the first character is typed, and the webhook is sent. Only the contact record ID number will be populated in the data payload with all other fields empty.
Lightweight: For Contacts and other Objects added by the API or by forms, the default data payload will include all fields. The data format "lightweight" returns only the record ID, first name, last name and email for the Contact Record. For a Custom Object, the record ID and first three custom fields are returned. This is useful if you would like the basic fields sent but don't need all of the fields in the record.
Webhook Subscription Errors
If the subscribed URL returns too many errors we suspend sending the data payload and unsubscribe the webhook. Testing is the developer's responsibility, but ONTRAPORT is happy to assist the developer. Provide a text file with your code and the exact error code you are receiving and attach it to an email to apisupport@ontraport.com. Include the account's API Key and Application ID.
Data payloads are sent in groups of 100 and threaded out to send, so some delays can be expected if hundreds of thousands of events are being reported.
Using API Docs for Webhook Subscriptions
Webhook documentation can be found in the API Doc. Two sections are found in the left column, Webhooks and Webhook Events. cURL and PHP examples are given.
You can use the API Live Doc Webhooks section to see if any webhook subscriptions exist, and to create subscriptions to Request.bin or other services as shown in the Testing Webhook Subscriptions section.
You need an API Key and Application ID from an active account to use the API Live Doc. Obtain a set in the account by clicking the profile menu at the top right, and selecting Administration > Integrations > ONTRAPORT API Instructions and Key Manager.
Enter the API Key and Application ID at the top, scroll down and expand the Get /Webhooks section. Near the bottom, click Try it out! (you don't need to enter any parameters). The response body will list the active webhook subscriptions (if any).
Testing Webhook Subscriptions
Using a service like RequestBin can allow you to test the webhook subscriptions without working directly on a file on your server.
- Obtain an Application Key and App ID for the ONTRAPORT account you will be using in the test. You can obtain it by clicking the profile icon at the top right, then Administration > Integrations > ONTRAPORT API Instructions and Key Manager.
- Enter the Application Key and App ID in the API Live Doc.
- Go to RequestBin and create a Request Bin. Copy the Bin URL to the clipboard.
- In the Live Doc, go to the Post /Webhook/subscribe section.
- Paste the Bin URL into the url field under Parameters.
- In the event field, use the webhook subscription Event Name. The following Event Names are available (the number in parenthesis is the ID number of the associated item):
- object_create(0)
- object_submits_form(0)
- sub_tag(0)
- unsub_tag(0)
- For this example, we will use sub_tag(0). We need a Tag ID for the "0" in parenthesis. To get the ID number of a Tag in the account:
- Navigate to the getTags section of the Live Doc.
- Click the Try it out! button (no parameters needed).
- Choose a "tag_id" number from the response body. In this example we are using this account's tag_id 3 for the tag "Password Change" (this will differ in each account).
- Enter the sub_tag(0) in the event field with the tag ID number you are using. This example is using sub_tag(3).
- Because we only want the basic fields returned we will use "{"format":"lightweight"}" in the data field.
- Click the Try it out! button to send the command. The Response Body section will show the results of the subscription.
- In the ONTRAPORT account, go to the Contacts Collection and select a Contact. Add the Tag the webhook is looking for using the Tags item in the action bar.
- Return to the RequestBin page and refresh it to see the data payload.
Subscribe to the API RSS Feed
ONTRAPORT pushes notification of all API changes to our API RSS Feed. Subscribe to it to have updates pushed to your favorite RSS reader.
Comments