Webhook Overview

Webhooks let PacSpace push events to your application in real time. Instead of polling for status updates, you register a URL and PacSpace sends an HTTP POST request whenever something important happens — like a delta being verified or a checkpoint being committed.

What Are Webhooks?#

A webhook is an HTTP callback. When an event occurs in PacSpace (e.g., your delta is verified), PacSpace makes a POST request to a URL you've configured, with a JSON payload describing the event.

Your server receives the payload, verifies the signature, and processes the event — no polling required.

Your App                    PacSpace
   │                           │
   │  POST /balance/delta      │
   │ ─────────────────────────→│
   │                           │ ← verification pipeline
   │                           │
   │  POST (your webhook URL)  │
   │ ←─────────────────────────│
   │  { event: "delta.verified", ... }
   │                           │

Setting Up Webhooks#

You can create webhooks through the Dashboard UI or the API.

Via the Dashboard#

1. Navigate to Settings → Webhooks in the PacSpace dashboard
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS in production)
4. Select the events you want to subscribe to
5. Save — PacSpace generates a webhook secret for signature verification

Via the API#

Create a webhook programmatically with a POST request:

curl -X POST https://api.pacspace.io/v1/dashboard/webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/pacspace",
    "events": ["delta.verified", "checkpoint.verified"]
  }'

Response:

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/pacspace",
  "events": ["delta.verified", "checkpoint.verified"],
  "secret": "whsec_k7x9m2p4q8r1t5v3...",
  "active": true,
  "createdAt": "2026-02-11T10:30:00Z"
}

Important: Store the secret value securely. You'll need it to verify webhook signatures. The secret is only shown once at creation time.

How Delivery Works#

When an event fires:

1. PacSpace serializes the event payload as JSON
2. PacSpace signs the payload with your webhook secret (HMAC-SHA256)
3. PacSpace sends a POST request to your URL with the payload and signature headers
4. Your server should respond with a 2xx status code within 30 seconds

Retry Policy#

If your endpoint doesn't respond with a 2xx status code, PacSpace retries with exponential backoff:

After 5 failed retries, the event is marked as failed. You can view and manually retry failed deliveries in the Dashboard.

Ordering#

Webhooks are delivered in the order events occur, but network conditions can cause out-of-order delivery. Use the deltaIndex field for ordering and the X-Event-ID header for deduplication.

Quick Start Checklist#

• Register a webhook endpoint (Dashboard or API)
• Store the webhook secret securely
• Implement signature verification
• Return 200 OK quickly, then process async
• Handle all event types you've subscribed to
• Use X-Event-ID for idempotent processing

Next Steps#

• Event Types — All events and when they fire
• Payload Reference — Detailed payload schemas
• Signature Verification — Verify webhook authenticity
• Autonomous Agent Pattern — Build agents that react to webhooks