How to parse, validate and handle webhooks and monitor their deliveries on Polar
Once a webhook endpoint is setup you will have access to the delivery overview page. Here you can:
Now, let’s integrate our endpoint route to validate, parse & handle incoming webhooks.
You now need to setup a route handler for the endpoint registered on Polar to receive, validate and parse webhooks before handling them according to your needs.
Our TypeScript & Python SDKs come with a built-in helper function to easily validate and parse the webhook event - see full examples below.
Both examples above expect an environment variable named POLAR_WEBHOOK_SECRET
to be set to the secret you configured during the endpoint setup.
We follow the Standard Webhooks standard which offers many libraries across languages to easily validate signatures. Or you can follow their specification in case you want to roll your own.
Note: Secret needs to be base64 encoded
One common gotcha with the specification is that the webhook secret is expected to be base64 encoded. You don’t have to do this with our SDK as it takes care of the implementation details with better developer ergonomics.
If we hit an error while trying to reach your endpoint, whether it is a temporary network error or a bug, we’ll retry to send the event up to 10 times with an exponential backoff.
We timeout our requests to your endpoint after 20 seconds. Triggering a retry attempt after a delay as explained above. However, we strongly recommend you optimize your endpoint route to be fast. A best practice is for your webhook handler to queue a background worker task to handle the payload asynchronously.
Seeing deliveries on Polar, but not receiving them on your end? Below are some common techniques to resolve the issue depending on the reported error status.
General
Start ngrok or similar
Make sure you have started ngrok
or whatever tunneling service you’re using
during local development.
Add excessive logging
E.g
console.log('webhook.handler_called')
,
console.log('webhook.validate_signature')
,
console.log('webhook.signature_validated')
etc.
So you can easily confirm if the handler is called and how far it gets before any issues arise.
HTTP 404
curl -vvv -X POST <copy-paste-endpoint-url>
in your terminal to confirm the
route exists and see any issues along the way/
to the URL on Polar. Often /foo
is resolved to
/foo/
by frameworks.HTTP 403
Rolling your own webhook validation logic? Make sure to base64 encode the secret you configured on Polar in your code before generating the signature to validate against.