Webhook URL Parameters

When working with webhooks in PolyAPI, you can capture data from both the URL path and query parameters, not just the request body.

Most webhooks receive data in the HTTP request body (Event Payload), but many systems also send information through URL path and query parameters. PolyAPI makes it easy to see and control how these URL parameters are processed!

Adding parameters to webhooks

When creating the webhook, scroll down to the subpath field and define the query and/ or path parameters for the webhook. This field explicitly shows the structure PolyAPI uses to parse parameters from the URL, including both path and query parameters. This allows you to preview exactly how incoming parameters will be extracted.

We can add parameters to a webhook as shown in the image below:

Webhook creation form in PolyAPI UI showing the subpath field with URL pattern /{userID}?country={countryName}&limit={lim}, demonstrating how to define path parameters in curly braces and query parameters with key=value pairs

How parameters are resolved

When a webhook is triggered, the connected Server Function is executed. The values passed to the function as a parameters object (path and query) and are resolved by merging parameters from the incoming URL against the Webhook Subpath template as shown below:

Parameter Resolution

Source

Example Subpath

Example Incoming URL

Resolution Logic

Parsed Params

Static Values

&meal=dinner

&meal=breakfast

Value is taken only from the template, overriding any caller value.

 
{
    "meal": "dinner"
  }

Dynamic Params

?param1={secretCode}

?param1=123

Value is taken from the URL, but the key is the renamed template key (secretCode).

 
{
    "secretCode": "123"
  }

Path Params

/{userID}

/987

Value is taken from the URL, but the key is the renamed template key (userID).

 
{
    "userID": "987"
  }

Remaining Caller Params

(Not in template)

&fruit=apple

Any parameters from the caller’s URL not defined in the template are passed through with their original key.

 
{
    "fruit": "apple"
  }

Executing a webhook with parameters in Canopy

In the PolyAPI UI, when you’re viewing or testing a webhook, the interface provides a clear structure for how information is extracted from the incoming URL.

Below is an example of testing parameters in the UI.

Webhook testing interface in PolyAPI UI showing a subpath field with pattern /{region}?country={countryName}&limit={lim}&num=5, with test input fields displaying region=wherePearsGrow, countryName=Genovia, and lim=50

These parameters will evaluate to:

{ "country": "Genovia", "region": "wherePearsGrow", "lim": 50, "num": 5 }

Note

The key or the name of the query parameter comes from the name passed into the template variable. i.e; the string inside the curly braces and NOT the string to the left of the equals sign.

Conclusion

That’s it! You now know how to:

  • Parse URL path and query parameters in your webhooks

  • Test webhooks with parameters from PolyUI

  • Understand how parameter resolution works when merging template and incoming values

For more on securing your webhooks, check out Webhook Security Functions.