Skip to main content

How to let only signed webhooks through to a path of a link

Since app version 1.4.0

On the tunnel's "Security" tab, in the "Webhooks" section, add a rule for the handler's path and paste the sender's secret: only requests with a correct signature get through to that path, and the rest are refused before they reach the service.

Only an HTTPS link with a reserved address has these rules: without one, the "Webhooks" section says "Needs a reserved address" (how long a link is kept). The first rule works on every plan, the next ones on Pro and Ultra.

Steps​

  1. Under "Tunnels", open a tunnel with an HTTPS link, its "Security" tab and the "Webhooks" section.
  2. Click "Add a webhook rule".
  3. In "Provider", pick the sender: Stripe, GitHub, T-Bank, CloudPayments, Slack, GitLab, Sentry, Linear or "Own HMAC".
  4. In "Path", enter the path the sender posts notifications to, for example /webhooks/stripe. Ending in /*, the rule also applies to everything below it.
  5. In "Secret", paste the sender's secret: the line under the field says which one, for example Stripe's signing secret, which starts with whsec_. For "Own HMAC", also fill in "Signature header", "Algorithm", "Encoding" and, if needed, "Signature prefix", for example sha256=.
  6. If needed, keep only the methods you need of POST, PUT and PATCH under "Methods", and set "Largest body": by default it is 25 MB for GitHub and GitLab, 256 KB for T-Bank and CloudPayments and 1 MB for the rest, and a request with a larger body is refused ("body too large").
  7. If the "Requests" tab already has a notification from this sender, pick it in "Check on a request from the journal": saving shows whether it was signed with this secret.
  8. Click "Add". The app says "Rule added", and the rule shows up under "Webhook rules".

In the list, the "Edit the rule …" and "Remove the rule …" icons change and delete a rule.

What else a rule does​

  • It lets through only its own path and closes the ones that look like it, for example /webhooks/stripe.json: accept webhooks only on the rule's path.
  • On a rule's path the rule alone decides: path rules and the link's login don't apply there.
  • While the address has a rule, a GET, HEAD, OPTIONS or TRACE request with a body is refused.
  • If Pro or Ultra ends, the second and later rules are suspended and their paths answer with error 503; the first rule keeps working. Renew the plan or remove the extra rules.
  • If you turn on "Only flag" in the rule's window, requests with a wrong signature reach the service, flagged on the "Requests" tab. On a link with a login, keys or path rules they are still refused.

Stripe, Slack, GitLab with a signing token and Linear sign the time: keep your computer's clock right. The others sign no time, so a genuine notification can be sent again: handle each one once by its id. T-Bank does not sign every field: before you hand over an order, check the payment as on the page about payment webhooks.

The rule and its secret live on this computer only. If another computer serves the same link, keep the path under the login there.

Check​

Send a test notification from the sender's dashboard: it shows up on the "Requests" tab with your service's answer. A request without a correct signature is refused, and the "Webhooks" section shows how many were refused and why, for example "wrong signature".