Retreaver Webhook Configurator

Integrations made easy

The Retreaver Webhooks Configurator works by structuring HTTP webhook requests using templates. Webhook templates can be used to easily analyze and modify webhooks, allowing for more transparency and control when managing your call campaign webhooks.

Webhook Integration Templates:

Media Alpha Ping for a Dynamic Endpoint

Ringba RTB Ping for a Dynamic Endpoint

Webhook Template Formatting Rules

What is URI Encoding?
URI encoding is the process of converting certain characters, such as spaces, quotes or special characters, into a format that can be transmitted over the internet. URI encoding is used to ensure that the characters in a URL are able to be transmitted and interpreted correctly by different systems. It allows URLs to contain characters that are not normally allowed, such as spaces or special characters, by representing them in a standard format. This helps prevent errors and ensures that URLs are interpreted and processed consistently across different platforms and systems.

Practical Example:
The "&" character typically represents the beginning of a new URL parameter, however what if you intended to pass along the following name in a webhook: "John&Sons" . This field would be treated as two separate properties rather than one property due to the unencoded "&" in the request. By encoding the "&" into its URI equivalent (%26) into the final result: "John%26Sons" - the field will now be sent as one individual property. 

Retreaver automatically handles some of the encoding for you, such as converting spaces into "%20" and quotes into "%22" once a webhook URL has been edited and saved. Be careful not to leave any trailing spaces or quotes in your templates as they will be URI encoded and potentially cause your webhooks to fail.

In summary, URL requests can behave differently depending on the circumstance and location of certain URL characters. The general rule is, encode every character listed in the table below if it is utilized within a webhook configuration parameter.

List of known special characters that require URI encoding

Special considerations when working with URL tools:
If you are using tools to pretty print URL's, or remove white spaces - be mindful as these tools can impact your template by either removing important space characters, such as the space between an authorization "bearer XYZ" token or removing <podd> operators as they are perceived as HTML. Always double check your webhook configuration template anytime these tools are utilized. 

P.O.D.D

Ping output dependent data, or PODD for short - are operators created to reference fields that are only available once a webhook ping step was triggered. PODD fields are typically used to confirm an event or action that was offered during a ping step.

In order to reference a podd field, you must utilize the "<podd_start>" and "<podd_end>" tokens. The PODD operators will then swap the provided outputmap key with the value returned by the ping request. The swapped value can then be used in your post webhook step.  

First example: If you received verification URL from a ping step that you need to post to in order to accept a bid, and you stored the response under a "confirmation_url" tag in your ping_output_map, your post URL parameter would appear as:

&post_url=<podd_start>confirmation_url<podd_end>

Second example: If you received a bid ID from a ping step that you need to send in the post data structure to accept a bid, and you stored the response under a "ping_bid_id" tag in your ping_output_map, your post_data parameter would appear as:

&post_data={"bid_id":"<podd_start>ping_bid_id<podd_end>"}

Please Note: If the value needs to be surrounded by quotes, surround PODD operators with quotes:
Example: <podd_start>tag_key<podd_end> ( This will output: swapped_value )
Example: "<podd_start>tag_key<podd_end>" ( This will output: "swapped_value" )

F.A.Q

Question: How do I test webhook templates I've created?

1) Add your webhook template into the URL portion of a webhook request
2) Set the webhook trigger to "when a call starts"
3) Make a test call to your Retreaver campaign:

Review our "Retreaver Webhook Overview" guide for more information. 

Question: How do I view the result of a webhook template?

View the pixel fired log on the call flow page to view all of your triggered webhooks. This will also show you the response of the webhooks that triggered as well.

Question: How do I troubleshoot a webhook template?

Reach out to Retreaver Support, we will assign a developer to review your configuration template by replicating the same request using an API tester such as "PostMan". If the request works using Postman, then it will also work using the exact same specifications on the webhook configurator template.

General Webhook Troubleshooting Guidelines:

1) If in doubt, double check all of your configuration parameters.
2) Check that JSON data structures are using the correct syntax.
3) Check that every field is spelled correctly and provided with a valid value.
4) Check that the system you are attempting to communicate with is online.
5) Check that your API credentials are correct and authorized to access the system.

Retreaver Support

If you have any questions about the Retreaver Webhooks Configurator, please open a support ticket.
The Retreaver support team will assist with implementing or troubleshooting any desired integrations. 

Be sure to include any relevant details such as:

Any source material containing webhook posting instructions, example: API Docs, API Specs etc. 
Any references to special values, example: API keys, Campaign ID's, Specific Custom Properties etc.
Any relevant Retreaver campaign links, example: [ https://retreaver.com/campaigns/12345 ].
Any relevant Retreaver buyers links, example: [ https://retreaver.com/call_buyers/12345 ].