Webhook Overview

Webhooks let PacSpace push events to your application. Instead of polling for status updates, you register a URL and PacSpace sends an HTTP POST request when something important happens.

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.

Your App                    PacSpace
   │                           │
   │  POST /balance/delta      │
   │ ─────────────────────────->│
   │                           │
   │                           │
   │  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. Save. PacSpace generates a webhook secret for signature verification

Via the API#

Create a webhook programmatically with a POST request:

curl -X POST https://app.pacspace.io/dashboard/webhooks \
  -b pacspace-dashboard-cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/pacspace"
  }'

Response:

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/pacspace",
  "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 linear backoff capped at 10 minutes:

After 10 failed attempts, 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 - Public payload examples
• Signature Verification - Verify webhook authenticity
• Autonomous Agent Pattern - Build agents that react to webhooks