Overview
The corsa-webhook-debugging skill teaches your AI coding assistant how to troubleshoot webhook integrations with Corsa. 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 AI assistant 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.