Retreaver Webhook Configurator

Introducing the Retreaver Webhooks Configurator

Webhooks allow applications to communicate with other systems by sending HTTP requests to a predefined URL. The receiving system can then use the data provided by the webhook to trigger additional work flows, this makes webhooks a popular way for services to communicate with each other in real-time.

For call tracking purposes, one could utilize webhooks to:

  • Send data from Retreaver to a database of your choice.
  • Verify or enrich caller data & check for validity or eligibility for a call campaign.
  • Communicate with a call center to verify if an agent is available to take a call.
  • Offer the call for sale through various auction systems and evaluate proposed bids.
  • Utilize the response of third party systems to influence call routing behaviour & much more!

The webhooks configurator allows users to implement their own integrations with ease.
Retreaver users can now build, analyze, tweak and troubleshoot their call tracking webhooks.

 

Retreaver Webhook Configuration Guide

How does the Retreaver Webhooks Configurator work?

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.

Existing Retreaver Webhooks Configurator Integration Templates You can Use
URI Encoding considerations

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 Character Encoded Symbol Description
? %3F Represents the beginning of URL parameters.
& %26 Represents a URL parameter key.
= %3D Represents a URL parameter value.
space %20 Represents a space character.
" %22 Represents a JSON property.
[ %5B Represents the beginning of a Retreaver tag token, and will be taken literally by Retreaver if enclosed and not encoded.
] %5D Represents the end of a Retreaver tag token, and will be taken literally by Retreaver if enclosed and not encoded.

 

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. 

 

Ping output dependent data considerations

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" )

Frequently Asked Questions

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:

Adding_Webhook_Template.png

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.

Webhooks Configurator Support

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 ].

 

Retreaver Webhooks Configurator Sample Template

https://retreaver.com/webhook-configurator/v1/?call_key=[call_key]&call_uuid=[call_uuid]
&output_tag_prefix=webhook_configurator
&ping_url=https://example.com/ping
&ping_method=POST
&ping_headers={"Content-Type":"application/json"}
&ping_data={"api_token":"ABC123","call_type":"health","caller_zip":"[caller_zip]"}
&ping_output_map={"PingOutputMap":{"ping_bid_id":"bid_response%5B0%5D.bid_id","ping_bid_value":"bid_response%5B0%5D.bid_value"}}
&return_ping_response=true
&send_post=true
&post_condition_key=ping_bid_value
&post_condition_operator=is_greater_than
&post_condition_value=0
&post_url=https://example.com/post
&post_method=POST
&post_headers={"Content-Type":"application/json"}
&post_data={"api_token":"ABC123","call_type":"health","caller_zip":"[caller_zip]","bid_id":"<podd_start>ping_bid_id<podd_end>"}
&post_output_map={"PostOutputMap":{"dynamic_transfer_number_tag":"bid.phone_number","conversion_timer_tag":"bid.conversion_timer","unmodified_bid_value":"bid.value","final_revenue_tag":"bid.value","final_payout_tag":"bid.value"}}
&return_post_response=true
&payout_output_tag=final_payout_tag
&payout_modifier_percentage=1.0
&revshare_output_tag=final_revenue_tag
&revshare_modifier_percentage=1.0
&ping_decode_url_parameters=true
&post_decode_url_parameters=true

 

 

List of Webhook Configurator Properties

URL Parameter Description Example Values
call_key The automatically generated call key token used to tag a specific call.  (Required)

[call_key]

call_uuid The automatically generated call uuid token used to identify a specific call. (Required)

[call_uuid]

output_tag_prefix The string prefix used to name the output tags of a configured webhook. (Required)

Any lower case string following a "snake_case" naming convention, example: "my_webhook" will prepend tags so that the output would appear as "my_webhook_response"

ping_url The URL representation of the HTTP ping destination.  (Required)

https://example.com/ping

ping_method The HTTP method used to send a webhook. (Optional)

POST/GET

ping_headers The HTTP headers used to provide additional information about the request or response, such as content type or authentication.

(Optional)
JSON Formatted Headers:

{"Content-Type":"application/json"}

ping_data The HTTP data used to provide information about the request or response, such as call type or caller details.

(Optional)
JSON Formatted Data:

{
"call_type":"health",
"caller_zip":"[caller_zip]"
}

ping_output_map The map representing the location of desired HTTP response output tags. The left field represents the pending output tag name, while the right field represents the location of the tag value given a successful HTTP response.

(Optional)
JSON Formatted Data:

{"PingOutputMap":{
"ping_bid_id":"bid_response[0].bid_id",
"ping_bid_value":"bid_response[0].bid_value"
}}

send_post The boolean value used to indicate if a follow up HTTP post request is desired. (Optional)
FALSE/TRUE
post_condition_key The tag name used to evaluate whether or not a follow up HTTP post request should be sent. (Optional)
ping_bid_value
post_condition_operator The operator used to evaluate whether or not the post condition key is true. 

(Optional)
is_greater_than,
is_less_than,
is_equal,
is_unequal,
exists

post_condition_value The value used to evaluate whether or not the post condition key is true. (Optional)
This value could be a numerical value, or a string representation, example: "success" or "100"
post_url The URL representation of the HTTP post destination.  (Optional)
https://example.com/post
post_method The HTTP method used to send a webhook. (Optional)
POST/GET
post_headers The HTTP headers used to provide additional information about the request or response, such as content type or authentication.

(Optional)
JSON Formatted Headers:

{"Content-Type":"application/json"}

post_data The HTTP data used to provide information about the request or response, such as call type or caller details.

(Optional)
JSON Formatted Data:

{
"api_token":"ABC123",
"call_type":"health",
"caller_zip":"[caller_zip]",
"bid_id":"<podd_start>ping_bid_id<podd_end>"
}

post_output_map The map representing the location of desired HTTP response output tags. The left field represents the pending output tag name, while the right field represents the location of the tag value given a successful HTTP response.

(Optional)
JSON Formatted Data:

{"PostOutputMap:{
"dynamic_transfer_number_tag":"bid.phone_number",
"conversion_timer_tag":"bid.conversion_timer",
"unmodified_bid_value":"bid.value",
"final_revenue_tag":"bid.value",
"final_payout_tag":"bid.value",
"final_conversion_timer_tag":"bid.conversion_timer",
}}

payout_output_tag The output tag that will store the modified payout value using the payout_modifier_percentage. (Optional)
This value should be a tag key listed in your HTTP output map, example: final_payout_tag
payout_modifier_percentage The percentage value used to multiply the payout_output_tag value with. (Optional)
Float value between 0.0 and 1.0
revshare_output_tag The output tag that will store the modified revshare value using the revshare_modifier_percentage. (Optional)
This value should be a tag key listed in your HTTP output map, example: final_revenue_tag
revshare_modifier_percentage The percentage value used to multiply the revshare_output_tag value with. (Optional)
Float value between 0.0 and 1.0
timer_offset_tag The output tag that will store the modified timer value using the timer_offset_modifier. (Optional)
This value should be a tag key listed in your HTTP output map, example: final_conversion_timer_tag
timer_offset_modifier
The seconds value that will be added to timer_offset_tag. (Optional)
Integer value between -999 and 999
ping_decode_url_parameters The boolean value used to indicate if the HTTP ping request contains URL parameters.  (Optional)
FALSE/TRUE
post_decode_url_parameters The boolean value used to indicate if the HTTP post request contains URL parameters.  (Optional)
FALSE/TRUE
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.