Webhook 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 workflows, which makes webhooks a popular way for services to communicate in real time.

For call tracking purposes, you can use webhooks to:

• Send data from Retreaver to a database of your choice.
• Verify or enrich caller data and check 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.
• Use the response of third-party systems to influence call routing behavior and 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.

How to use the Webhook Configurator

The webhook configurator can be accessed when creating a webhook:

You can select a webhook template using the template dropdown highlighted in green.

The webhook configurator can automatically tag your buyers with any relevant webhook response tags using the Auto-setup buyer tags toggle highlighted in purple:

When you enable the Auto-setup toggle, a Call Buyer dropdown menu appears. This allows you to specify which buyer profile the webhook integration is intended for. Once a call buyer is selected, a list of pending tag changes relevant to the integration will be shown.

Once the webhook is created, Retreaver will automatically generate a webhook integration with your chosen API platform and tag the selected buyer profile with any relevant tag routing conditions and conversion criteria.

No more having to create complex webhook integrations from scratch.

No more manually tagging and mapping buyers.

Retreaver is excited to see which webhook integrations you will create next.

How does the Retreaver Webhooks Configurator work?

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

Available Webhook Templates

We offer the following webhook templates to help make adding webhook pixels easier to 3rd party platforms.

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 ensures that URL characters are interpreted consistently across different platforms and systems.

Practical example: The & character typically represents the beginning of a new URL parameter. If you intended to pass John&Sons in a webhook, the unencoded & would split the value into two parameters. Encoding the & into %26 results in John%26Sons, which is sent as a single value.

Retreaver automatically handles some 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 trailing spaces or quotes in your templates, as they will be encoded and could cause webhooks to fail.

In summary, URL requests can behave differently depending on where certain URL characters appear. The general rule is to encode every character listed in the table below if it is used 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 URLs or remove whitespace, be mindful that these tools can alter your template. For example, they may remove the space in an authorization token like bearer XYZ or strip <podd> operators because they are treated as HTML. Always double check your webhook configuration template if you use these tools.

Ping output dependent data (PODD)

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

To reference a PODD field, use the <podd_start> and <podd_end> tokens. The PODD operators swap the output map key with the value returned by the ping request, which you can then use in your post webhook step.

Example 1: If you received a verification URL from a ping step and stored it 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>

Example 2: If you received a bid ID from a ping step and stored it 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 the PODD operators with quotes.

<podd_start>tag_key<podd_end>
"<podd_start>tag_key<podd_end>"

Frequently Asked Questions

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.

How do I view the result of a webhook template?

View the pixel fired log on the call flow page to see all triggered webhooks and their responses.

How do I troubleshoot a webhook template?

Reach out to Retreaver Support. A developer can review your configuration template by replicating the request using an API tester such as Postman. If the request works in Postman, it will also work using the same specifications in 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 use 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

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 (API docs, API specs, etc.).
• Any references to special values (API keys, campaign IDs, specific custom properties, etc.).
• Any relevant Retreaver campaign links (for example, https://retreaver.com/campaigns/12345).
• Any relevant Retreaver buyers links (for example, https://retreaver.com/call_buyers/12345).

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"}}
&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"}}
&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