In a Sinatra payment-webhook receiver, how would you use a before filter and a helper to reject requests whose signature fails to verify?

## Filters, helpers and the request instance A **filter** is a block Sinatra runs around the routes. `before` blocks run ahead of the matching route and `after` blocks behind it. Both accept an optional path pattern, `before '/webhooks/*'`, and the same conditions routes take; without a pattern a filter runs for every request. A **helper** is an ordinary instance method. `helpers do ... end` evaluates the block inside the application class, and `helpers SignatureHelpers` includes a module, so the methods are callable from routes, filters and templates alike. What ties these together is **the instance they run on**. The class-level `call` hands each request to a prototype instance, whose `call` does `dup.call!(env)`. Every request therefore gets its own copy of the application object, and its before filters, route, templates and after filters all run with that copy as `self`. That is why an instance variable set in a before filter, such as `@payload`, is visible in the route, and why two concurrent requests on a threaded server cannot see each other's. ## The order of execution For each request Sinatra: 1. serves a matching file from `public_folder` if static serving is on; 2. runs the `before` filters, superclass filters first, then in definition order, each only when its pattern matches; 3. runs the first matching route; 4. runs the `after` filters from an `ensure` clause, so they run whether the route returned, halted or raised (only a request answered by a static file skips them). ## The webhook receiver ```ruby before '/webhooks/*' do @payload = request.body.read # raw bytes, read once verify_signature!(@payload) # may halt 401 end post '/webhooks/payments' do event = JSON.parse(@payload) halt 422 unless event['id'] 204 end ``` The helper computes `OpenSSL::HMAC.hexdigest('SHA256', secret, payload)`, takes the provider's signature from `env`, and compares them with `Rack::Utils.secure_compare`, a comparison whose time does not depend on where the strings differ. On a mismatch it calls `halt 401, 'bad signature'`. Why sign the **raw** body: the provider signed bytes, not a parsed Hash. Parsing and re-serialising can reorder keys or change whitespace, and the signature no longer matches. Reading it in the filter and storing it in `@payload` also avoids a second `request.body.read`, which at end of input returns an empty string. This works for a JSON body because Sinatra does not parse JSON into `params`. ## Why a filter and not a call in each route A receiver often grows one route per provider or per event family: `post '/webhooks/payments'`, `post '/webhooks/refunds'`. Calling `verify_signature!` at the top of each route works, but the first route someone adds without it is unauthenticated. A `before '/webhooks/*'` filter puts the check on the path prefix, so every current and future webhook route is covered and the routes contain only business logic. The filter still lives inside the Sinatra app, next to the routes it protects. The alternative, a separate Rack middleware placed in front of the app, suits a check that several applications share; the filter suits one that belongs to this app alone. ## What stops a request and what does not | Inside a before filter | Effect | |---|---| | return `false` or `nil` | ignored; the next filter and the route still run | | `halt 401, 'bad signature'` | remaining before filters and the route are skipped; after filters run | | `pass` | ends only this filter; the next filter and the route still run | | `raise` an exception | Sinatra's error handling takes over, a 500 unless a handler says otherwise | `halt` works from inside a helper because it is `throw :halt`: Ruby unwinds every method frame between the `throw` and Sinatra's `catch(:halt)`, so there is no need to check a return value in the filter. ## Pitfalls in review - **An unscoped filter.** `before do` also runs for a health check or a static asset; scope verification with a pattern. - **Comparing with `==`.** Its running time can depend on how many leading bytes match, which leaks information; use `Rack::Utils.secure_compare`. - **Relying on a return value.** Only `halt` (or `error`, `not_found` and `redirect`, which call it) stops the request. - **Parsing before verifying.** Verify the signature on the exact bytes first, then call `JSON.parse`. - **Logging in the route.** A rejected request never reaches it; an `after '/webhooks/*'` filter sees every final status, 401 included.