Documentation Index
Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The corsa-webhook-debugging skill adds Corsa webhook knowledge to your coding tool (Cursor, Claude Code, VS Code, etc.) so it can help you troubleshoot webhook integrations. It covers signature verification, delivery mechanics, event types, and common failure patterns.What It Helps With
- Diagnosing signature verification failures
- Identifying why events are not being received
- Handling duplicate deliveries with idempotency keys
- Setting up correct Express/Node.js webhook handlers
- Understanding Corsa’s delivery behavior (timeouts, retries, URL restrictions)
Quick Start
After installing the skill, ask your coding tool questions like:- “My Corsa webhook signature verification keeps failing”
- “I’m not receiving any webhook events from Corsa”
- “How do I handle duplicate webhook deliveries?”
- “Set up a webhook handler with proper signature verification”
- “What headers does Corsa send with webhooks?”
What the Skill Knows
Signature Verification
- HMAC SHA256 over the raw request body — format:
sha256=<hex> - Header:
x-hub-signature-256 - Why
express.raw()is required (re-stringified JSON differs from original bytes) verifyWebhookSignatureis synchronous (returnsboolean, not aPromise)- Constant-time comparison via
crypto.timingSafeEqual
Delivery Behavior
| Property | Value |
|---|---|
| Timeout | 5 seconds |
| Redirects | Not followed (3xx = failure) |
| Retries | Up to 3 retries with 10s delay |
| Total attempts | 4 (initial + 3 retries) |
| Protocol | HTTPS only |
| URL restrictions | Must have TLD, no raw IPs, no explicit port numbers |
All Webhook Headers
| Header | Purpose |
|---|---|
x-hub-signature-256 | HMAC SHA256 signature |
x-hook-id | Webhook configuration ID |
x-hook-delivery | Unique delivery ID (idempotency key) |
x-hook-event | Event type |
x-request-id | Request trace ID |
x-request-origin | WEB or API |
All 24 Event Types
Clients, corporate clients, alerts, cases, transactions, deposits, withdrawals, trades, individual members, corporate members, blockchain wallets, and bank accounts — each with.created and .updated variants.
Payload Structure
- Created events:
type,timestamp,data.id,data.referenceId,data.entity - Updated events:
type,timestamp,data.id,data.referenceId,data.updated,data.previousValues
Common Failures It Diagnoses
| Symptom | What the skill checks |
|---|---|
| Invalid signature | Body parsed before verification, wrong secret, modified body, encoding issues |
Missing x-hub-signature-256 header | Webhook created without a signing secret |
| Events not received | Webhook inactive, event not subscribed, URL validation failed, DNS resolution |
| Timeouts | Handler takes longer than 5s — suggests async processing |
| 3xx errors | Redirects not followed — URL must return 200 directly |
| Duplicate events | Missing idempotency check on x-hook-delivery header |
Source
GitHub Repository
View the full skill source with detailed debugging guides and code examples.