webhook.rodeowebhook.rodeo

Challenge Verification

Some webhook providers require you to verify ownership of your webhook URL before they'll send events to it. This is called challenge verification or URL verification. webhook.rodeo handles this automatically—no configuration needed.

What is challenge verification?

When you register a webhook URL with certain providers, they send a verification request to confirm:

  1. You own the URL - The endpoint exists and you control it
  2. The URL is responsive - It can receive and respond to requests
  3. The integration is correct - Your endpoint understands their protocol

This prevents attackers from registering arbitrary URLs and protects both you and the provider.

How providers implement it

Providers typically send a challenge value and expect you to echo it back. If your response matches, the webhook URL is verified and the provider starts sending real events.

Supported providers

webhook.rodeo automatically detects and responds to challenge verification requests from any provider that uses these common patterns:

GET query parameter (Nylas-style)

Providers send a GET request with a challenge query parameter. webhook.rodeo responds with the exact challenge value as plain text.

Nylas-style (?challenge=):

GET /w/you/webhook-name?challenge=abc123xyz

Meta-style (?hub.challenge=):

GET /w/you/webhook-name?hub.mode=subscribe&hub.challenge=1158201444&hub.verify_token=mytoken

webhook.rodeo responds with the exact challenge value as plain text:

abc123xyz

Providers using this pattern:

POST body JSON (Slack-style)

Providers like Slack send a POST request with the challenge in the JSON body:

{
  "type": "url_verification",
  "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P",
  "token": "Jhj5dZrVaK7ZwHHjRyZWjbDl"
}

webhook.rodeo responds with the challenge value as plain text (Slack accepts text/plain, JSON, or form-urlencoded):

3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P

Providers using this pattern:

How it works

webhook.rodeo automatically detects challenge verification requests by checking:

  1. GET requests with a challenge query parameter
  2. POST requests with JSON body containing a challenge field

When detected, webhook.rodeo:

  1. Logs the challenge as a special event (so you can see it happened)
  2. Responds immediately with the correct format
  3. Returns the exact challenge value the provider expects

No forwarding occurs for challenge requests—the response is sent directly to the provider.

Challenge verification is always enabled and requires no configuration. Your webhooks are ready to pass verification as soon as you create them.

What about real events?

After verification succeeds, the provider switches to sending real webhook events via POST. These are processed normally:

  • Captured and logged
  • Forwarded to your destination URL (if configured)
  • Signature verified (if you have a secret configured)

Challenge events are clearly labeled in your event history so you can distinguish them from real webhook events.

Viewing challenge events

Challenge verification requests appear in your event history with a distinctive Challenge badge. This helps you:

  • Confirm verification succeeded - See that the provider's challenge was handled
  • Debug setup issues - Verify challenge requests are reaching your webhook
  • Audit activity - Track when webhooks were verified or re-verified

In the event details, challenge events show:

  • The challenge value that was received
  • When the verification occurred
  • The source IP of the provider

Challenge events don't have forwarding information since they're handled directly by webhook.rodeo.

Cryptographic challenges (not yet supported)

Some providers require a more complex challenge-response that involves cryptographic signing:

  • Zoom - Requires HMAC-SHA256 signed response with both plainToken and encryptedToken

If you need to integrate with a provider using cryptographic challenges, please contact support and we'll help you find a solution.

Getting help

Challenge not being detected?

If a provider says your webhook URL failed verification:

  1. Check the webhook is active - Inactive webhooks reject all requests, including challenges
  2. Verify the URL is correct - The provider must use https://webhook.rodeo/w/username/webhook-name
  3. Look for the challenge event - If it's in your event history, we received it

Provider uses a different format?

Some providers use non-standard challenge formats. If you're having trouble:

  1. Check the provider's documentation - Note what format they expect
  2. Send us the details - Email support@webhook.rodeo with:
    • Provider name and documentation link
    • Expected request/response format
    • Your webhook name

We can add support for additional challenge formats—let us know what you need!

Contact support

If you're still having verification issues, email us at support@webhook.rodeo with:

  • Your webhook name
  • The provider you're trying to connect
  • Any error messages from the provider
  • Screenshots of the provider's webhook configuration

We're happy to help debug and ensure your webhooks verify successfully.

Was this page helpful?