Skip to content
PayloadPuffin.
Join the waitlist

Answer URL checks

Some providers won't send webhooks to a URL until it answers a check. Meta sends a GET with a verify token you chose and expects a challenge value back. Slack sends a signed POST with "type": "url_verification" and expects its challenge. A source can answer both, and an answered check never becomes an event.

Set up a check

In the console, select the source and click Edit URL checks. With the API, set a check with Set the GET URL check of a source or Set the POST URL check of a source, and stop answering one with the matching DELETE.

GET query, as Meta sends

The GET check takes three fields:

  • tokenParameter: the query parameter with the verify token, hub.verify_token for Meta.
  • token: the verify token you entered at the provider.
  • challengeParameter: the parameter whose value is the answer, hub.challenge for Meta.
Shell
curl -X PUT "https://api.payloadpuffin.com/v1/sources/$SOURCE_ID/query-challenge" \
  -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tokenParameter": "hub.verify_token", "token": "my-verify-token", "challengeParameter": "hub.challenge"}'

A GET whose token matches gets 200 with the challenge value as plain text. Any other GET gets the same 404 as a wrong URL. A GET is never signature-checked, because Meta doesn't sign its check.

POST body, as Slack sends

The POST check takes three fields:

  • member: the top-level JSON member to match, type for Slack.
  • value: the value it has in a check, url_verification for Slack.
  • echo: the member whose value is the answer, challenge for Slack.

A POST passes signature verification first, if the source has one. Then, when its JSON body is at most 4 KiB and the member matches, it gets 200 with the echo member's value as plain text. Any other POST is stored as an event as usual.