A webhook is an endpoint you create in Ringba so outside systems can send conversion data into your Ringba account. Webhooks are primarily used for offline conversions. However, they can also support performance-based routing, enhanced reporting, and further insight into your call flows. For example, you can create a webhook to let your buyer send conversion information about whether a call converted, how much revenue it earned, plus additional tag data.

Creating a Webhook

Use the following steps to create a Ringba webhook:

Tip: If your buyer uses Ringba, you can simply complete the Name field and save the webhook. You can use the same webhook for multiple buyers, as long as they conform to the same standards.

1. Navigate to Integrations > Webhooks in the left navigation panel.
2. Click Create Webhook.
   
3. Complete the fields on the webhook
   
   • Name: Enter the name of the webhook. This name helps you identify the webhook information on the report.
   • Call Token: Enter the name of the URL parameter that contains the inbound call ID. This ID uniquely identifies the call the request applies to.
   • Revenue Token: Enter the name of the URL variable that will contain the revenue amount.
   • Fire Conversions: Enter the name of the variable that must be present in order for Ringba to fire the associated conversion. If the buyer has a Ringba account, this field is required and you can leave the value at the default setting. This field is optional for other buyers.
     Note: If you leave the Fire Conversion field blank, Ringba records a conversion for every call whose data you send to the webhook, even if the revenue token contains 0.00. If you do not want Ringba to record $0-revenue calls as converted, you should enter a value in this field and include the token in your call with a value of no. Alternatively, you can suppress sending $0-revenue calls to the webhook.
4. Click Create to create and save the webhook.

Now that you have your webhook created, don't forget to make sure your target is set to convert on Postback/Webhook.

For static targets, you do this in the campaign. Choose postback/webhook in the Convert On field when you add a target in the Routing Plan section.

For ring tree targets, you do this in the ring tree. Choose postback/webhook in the Convert On field in the Revenue Settings section.

Provide the Webhook to Your Buyer

After you create the webhook, the screen shows you the URL your buyer can use to pass data to Ringba. You share this URL with your buyers so they can set up their requests to the webhooks API. The URL looks something like this:

https://webhook.ringba.com/hook/<WebhookID>?call_id=[callUUID]&call_revenue=[conversionAmount]&sale_successful=yes

Note: If you are using shareable tags to send the inbound call ID to the buyer, the buyer should replace the [callUUID] on the webhook URL with [tag:user:publisherInboundCallId] and [conversionAmount] with [Call:ConversionPayout]. Check our article on Shareable Tags between Ringba Accounts for more details.

Getting the Inbound Call ID to Your Buyer

The first and most important item a webhook call must contain is the inbound call ID. This is the ID assigned to every call routed through the Ringba system. You can get the inbound call ID to your buyer in the following ways:

1. Using SIP. If you're using SIP, all you need to do is tell your buyer that Ringba adds a Call Token to every call routed to a SIP target. Ringba passes a unique token in every SIP header, and this ID is then captured by the target's system.
2. Firing a pixel. The inbound call ID token to attach to the pixel is [Call:InboundCallId].
3. To send the inbound call ID to a buyer that also has a Ringba account, you must enable the Shareable Tags feature and toggle on the Share Inbound Call ID switch.
4. Sending using a ring tree target. The inbound call ID token to attach to the ring tree target is [Call:InboundCallId]. 

Once the buyer's system has captured the ID, that system can use it with the Ringba webhook URL to pass revenue data into Ringba.

Confirming Conversions Succeeded

Calls that connect to a target that is configured for postback/webhook initially have no revenue associated with them. See below. 

After your buyer has sent the conversion data to your webhook, you see the revenue in the reporting.

Webhooks FAQ and Troubleshooting

Can a call that has converted on webhook be updated again via the webhook? 

No. A webhook conversion can happen only once for each inbound call ID. If the buyer records a conversion and then later tries to send the conversion again, the system returns an error.

Why is my buyer getting a 404 error in response to a webhook request?

Most times, a 404 error appears when a buyer tries to send a second conversion request to the webhook. A buyer can use the webhook to convert each inbound call ID a maximum of one time. Any attempts to request a conversion for the inbound call ID after the first result in a 404 error.

What should I do if I don't want $0 revenue calls to be recorded as "converted"?

If you include a Fire Conversion token in your call to the webhook API, you can set that token to no to avoid recording a conversion. If you do not include the token, you must suppress sending $0-revenue call data to the webhook because Ringba defaults to assuming a call to the webhook represents a conversion.

Can I use the same webhook for multiple buyers and campaigns?

Yes, if your buyers can send the call information using the tokens you configure, then you can use the same webhook for multiple or all of your buyers. The request to the webhook API includes the inbound call ID, so Ringba can identify the call regardless of which buyer it came from.

However, if you have a buyer that must use different tokens, you should create a separate webhook for that buyer.

What should I do if I need help with webhooks?

If you have any questions or need additional help, please reach out to our support team via chat or email at support@ringba.com.