CodeWall Documentation

Create and manage webhook endpoints to receive real-time notifications when events occur on the platform.

Endpoints

Method	Endpoint	Description
`POST`	`/v1/webhook-endpoints`	Create a new webhook endpoint
`GET`	`/v1/webhook-endpoints`	List all webhook endpoints
`GET`	`/v1/webhook-endpoints/:id`	Get endpoint details
`PATCH`	`/v1/webhook-endpoints/:id`	Update an endpoint
`DELETE`	`/v1/webhook-endpoints/:id`	Delete an endpoint
`POST`	`/v1/webhook-endpoints/:id/test`	Send a test event
`GET`	`/v1/webhook-endpoints/:id/deliveries`	List delivery history

Create a webhook endpoint

curl -X POST https://api.codewall.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/codewall",
    "event_types": ["finding.created", "run.completed"],
    "secret": "your-signing-secret-min-16-chars",
    "channel_type": "webhook"
  }'

Field	Type	Required	Description
`url`	string	Yes	The URL to receive webhook deliveries
`event_types`	string[]	Yes	Events to subscribe to (see below)
`secret`	string	For `webhook` type	Signing secret (16–256 characters) for HMAC verification
`channel_type`	string	No	`webhook` (default), `slack`, or `teams`
`description`	string	No	Human-readable description

Channel types

Type	Description
`webhook`	Standard HTTP POST with HMAC signing. Requires a `secret`.
`slack`	Posts to a Slack incoming webhook URL. No signing secret needed.
`teams`	Posts to a Microsoft Teams incoming webhook URL. No signing secret needed.

Events

Event	Trigger
`finding.created`	A new vulnerability was discovered
`finding.high`	A high or critical severity finding was discovered
`run.completed`	A test run finished successfully
`run.failed`	A test run encountered an unrecoverable error
`approval.required`	A phase or command approval gate is waiting for a decision

Payload format

{
  "id": "evt_abc123",
  "event": "finding.created",
  "timestamp": "2026-04-10T10:30:00Z",
  "data": {
    "id": "find_abc123",
    "title": "SQL Injection in /api/users",
    "severity": "critical",
    "cvss": 9.8,
    "cwe": "CWE-89",
    "run_id": "run-20260410-103000-a1b2c3d4",
    "target": "https://example.com"
  }
}

Signature verification

Each delivery to a webhook channel includes an X-CodeWall-Signature header containing an HMAC-SHA256 signature:

X-CodeWall-Signature: sha256=abc123...

Verify it by computing HMAC-SHA256 of the raw request body using your webhook secret:

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry policy

Failed deliveries (non-2xx response or timeout) are retried:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes

After 3 failed retries, the delivery is marked as failed. View failed deliveries via GET /v1/webhook-endpoints/:id/deliveries.

Test a webhook

Send a test event to verify your endpoint is receiving deliveries correctly:

curl -X POST https://api.codewall.ai/v1/webhook-endpoints/:id/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Delivery history

View recent delivery attempts for an endpoint:

curl "https://api.codewall.ai/v1/webhook-endpoints/:id/deliveries?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Endpoints API