> ## 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.

# Webhook Debugging Skill

> AI skill for debugging Corsa webhook delivery, signature verification, event handling, and common failure modes.

## 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)
* `verifyWebhookSignature` is synchronous (returns `boolean`, not a `Promise`)
* 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 32 Event Types

Individual clients, corporate clients, alerts, cases, transactions, deposits, withdrawals, trades, individual members, corporate members, blockchain wallets, bank accounts, and payment accounts — each with `.created` and `.updated` variants (26 events). Checklists fire `.created` and `.updated` (2 events). Attachments fire `.created`, `.updated`, and `.deleted` (3 events). Forms fire `form_template.public_form_submitted` (1 event).

### 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

<Card title="GitHub Repository" icon="github" href="https://github.com/corsa-labs/corsa-skills/tree/main/corsa-webhook-debugging">
  View the full skill source with detailed debugging guides and code examples.
</Card>