> ## Documentation Index > Fetch the complete documentation index at: https://staging-docs.crosspoint.finance/llms.txt > Use this file to discover all available pages before exploring further. # Handle & monitor webhook deliveries > How to parse, validate and handle webhooks and monitor their deliveries on Crosspoint ![](https://mintcdn.com/crosspoint/UQs51vKfpD2N4tlw/assets/integrate/webhooks/delivery.light.png?fit=max\&auto=format\&n=UQs51vKfpD2N4tlw\&q=85\&s=f8551425cd798691021112636f778e24) Once a webhook endpoint is setup you will have access to the delivery overview page. Here you can: * See historic deliveries * Review payload sent * Trigger redelivery in case of failure Now, let's integrate our endpoint route to validate, parse & handle incoming webhooks. ## Validate & parse webhooks You now need to setup a route handler for the endpoint registered on Crosspoint to receive, validate and parse webhooks before handling them according to your needs. ### Using our SDKs Our TypeScript & Python SDKs come with a built-in helper function to easily validate and parse the webhook event - see full examples below. ```typescript icon="square-js" JS (Express) theme={null} import express, { NextFunction, Request, Response } from 'express' import { webhooks } from '@crossdev/sdk/2026-10' const app = express() app.post( '/webhook', express.raw({ type: 'application/json' }), async (req: Request, res: Response, next: NextFunction) => { try { const event = await webhooks.validateEvent( req.body, { 'webhook-id': req.header('webhook-id') ?? '', 'webhook-timestamp': req.header('webhook-timestamp') ?? '', 'webhook-signature': req.header('webhook-signature') ?? '', }, process.env['CROSSPOINT_WEBHOOK_SECRET'] ?? '', ) // Process the event res.status(202).send('') } catch (error) { if (error instanceof webhooks.WebhookVerificationError) { res.status(403).send('') return } if (error instanceof webhooks.WebhookUnknownTypeError) { // Event type added after this SDK version: acknowledge it so Crosspoint doesn't retry res.status(202).send('') return } next(error) } }, ) ``` ```python Python (Flask) theme={null} import os from flask import Flask, request from crosspoint.v2026_10.webhooks import ( WebhookUnknownTypeError, WebhookVerificationError, validate_event, ) app = Flask(__name__) @app.route('/webhook', methods=['POST']) def webhook(): try: event = validate_event( request.get_data(), dict(request.headers), os.getenv('CROSSPOINT_WEBHOOK_SECRET', ''), ) # Process the event return "", 202 except WebhookVerificationError: return "", 403 except WebhookUnknownTypeError: # Event type added after this SDK version: acknowledge it so Crosspoint doesn't retry return "", 202 ``` Both examples above expect an environment variable named `CROSSPOINT_WEBHOOK_SECRET` to be set to the secret you configured during the endpoint setup. ### Custom validation Use a [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries) or follow the [specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md). Secrets generated on or after 8 September 2026, 00:00 UTC are Standard Webhooks. Older secrets are Crosspoint HMAC. > [!NOTE] > > **Signing schemes** > > Crosspoint sends one `webhook-signature`. The HMAC key is which secret you have. > > **Before 8 September 2026, 00:00 UTC:** Crosspoint HMAC. Key is the UTF-8 bytes of > the full `whsec_…` string. Base64-encode that string before you hand it to a > Standard Webhooks library. > > **On or after that instant:** [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md). > Pass the `whsec_…` secret to the library as-is. > > Crosspoint SDKs 1.0.0-alpha.19 and later try both keys. Pass the `whsec_…` secret > from the dashboard. ## IP Allowlist Crosspoint sends webhooks from fixed IP addresses. If your firewall or reverse proxy only accepts requests from known IPs, email [support@crosspoint.finance](mailto:support@crosspoint.finance) and we'll send you the current list for live and sandbox. ## Failure Handling ### Delivery Retries 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. ### Delivery Timeouts We currently timeout our requests to your endpoint after **10 seconds**, triggering a retry attempt after a delay as explained above. However, we strongly recommend you optimize your endpoint route to respond within **2 seconds** to ensure reliable delivery. We may lower the timeout threshold in the future, so we advise implementing your webhook handler to queue a background worker task to handle the payload asynchronously. ### Endpoint Disabling Webhook endpoints are automatically disabled after **10 consecutive failed deliveries** (non-2xx responses). When this happens: * The endpoint is marked as disabled and will no longer receive new events. * All organization members will receive an email notification. To re-enable a disabled endpoint, open your organization's [webhook settings](https://app.crosspoint.finance/to/dashboard/settings/webhooks) and manually enable it. Before re-enabling, ensure your endpoint is properly configured and reachable to avoid repeated disabling. ## Troubleshooting ### Not receiving webhooks Seeing deliveries on Crosspoint, 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` * Try `curl -vvv -X POST ` in your terminal to confirm the route exists and see any issues along the way * Try adding trailing `/` to the URL on Crosspoint. Often `/foo` is resolved to `/foo/` by frameworks. `HTTP 3xx` Redirect responses (301, 302, 307, etc.) are treated as failures. Crosspoint does not follow redirects for webhook deliveries. Update your webhook URL to the final destination URL to avoid redirects. A common cause is hosting providers like Vercel that redirect between `www` and non-`www` domains. Make sure your configured URL matches your actual domain. `HTTP 403` * Using middleware for authorization? Make sure to exclude the webhook route from it since it needs to be publicly accessible * Using Cloudflare? * Check the firewall logs to verify if they are blocking our requests and setup a custom WAF rule to accept incoming requests from Crosspoint. * Webhook delivery failures with 403 errors can occur when Cloudflare's Bot Fight Mode is enabled. Bot Fight Mode automatically blocks requests it identifies as bots, including legitimate webhook requests from Crosspoint. Adding Crosspoint's IP addresses to your IP Allow List or creating custom WAF rules will not resolve this issue. To fix webhook delivery problems, disable Bot Fight Mode in your Cloudflare dashboard under Security > Bots. Alternatively, you can check your Cloudflare firewall logs to confirm if requests are being blocked and create appropriate firewall rules if needed. ### Invalid signature exceptions Rolling your own validation? Older secrets are Crosspoint HMAC: base64-encode the entire `whsec_…` string. Secrets generated on or after 8 September 2026, 00:00 UTC are Standard Webhooks: pass the secret as-is. Crosspoint SDKs 1.0.0-alpha.19 and later try both. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.