Webhooks - 9Squid

Webhooks deliver real-time event notifications to your server whenever something happens on the platform — a deal status changes, a loan is approved, a trade settles. This recipe shows how to subscribe, verify delivery, and replay failed events.

Overview

POST /webhooks/subscriptions          → create a subscription
GET  /webhooks/subscriptions          → list your subscriptions
GET  /webhooks/deliveries             → view delivery history
POST /webhooks/deliveries/:id/replay  → replay a failed delivery
DELETE /webhooks/subscriptions/:id   → remove a subscription

Step 1 — Create a Subscription

Point the platform at your endpoint and specify which events to receive. If you omit events, you’ll receive all event types.

curl -X POST https://api.9squid.com/v1/api/webhooks/subscriptions \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/9squid",
    "events": ["deal.status_changed", "loan.approved", "trade.settled"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "clxsub001",
    "url": "https://your-server.com/webhooks/9squid",
    "events": ["deal.status_changed", "loan.approved", "trade.settled"],
    "secret": "whsec_abc123xyz",
    "created_at": "2026-04-15T10:00:00Z"
  }
}

Save the secret — it is only shown once. Use it to verify webhook signatures on incoming requests.

Available Events

Event	Triggered when
`deal.status_changed`	A deal moves to a new status (e.g. `IN_REVIEW` → `QC_COMPLETED`)
`loan.approved`	A loan deal is approved for securitization
`loan.rejected`	A loan deal is rejected
`trade.settled`	An investor trade reaches settlement
`sc.completed`	A Selection Criteria job finishes
`document.uploaded`	A document is successfully uploaded to the deal room

Step 2 — List Your Subscriptions

curl https://api.9squid.com/v1/api/webhooks/subscriptions \
  -H "Authorization: Bearer <your_token>"

Response

{
  "success": true,
  "data": [
    {
      "id": "clxsub001",
      "url": "https://your-server.com/webhooks/9squid",
      "events": ["deal.status_changed", "loan.approved", "trade.settled"],
      "created_at": "2026-04-15T10:00:00Z"
    }
  ]
}

Step 3 — View Delivery History

Check which events have been delivered and whether they succeeded.

curl https://api.9squid.com/v1/api/webhooks/deliveries \
  -H "Authorization: Bearer <your_token>"

Response

{
  "success": true,
  "data": [
    {
      "id": "clxdlv001",
      "subscription_id": "clxsub001",
      "event": "deal.status_changed",
      "status": "DELIVERED",
      "http_status": 200,
      "attempts": 1,
      "created_at": "2026-04-15T11:00:00Z"
    },
    {
      "id": "clxdlv002",
      "subscription_id": "clxsub001",
      "event": "loan.approved",
      "status": "FAILED",
      "http_status": 503,
      "attempts": 3,
      "created_at": "2026-04-15T11:05:00Z"
    }
  ]
}

Step 4 — Replay a Failed Delivery

If a delivery failed (your server was down, returned a non-2xx, etc.), you can trigger a replay:

curl -X POST https://api.9squid.com/v1/api/webhooks/deliveries/clxdlv002/replay \
  -H "Authorization: Bearer <your_token>"

Response

{
  "success": true,
  "data": {
    "delivery_id": "clxdlv003",
    "status": "PENDING"
  }
}

A new delivery attempt is queued. Check delivery history after a moment to confirm the result.

Step 5 — Remove a Subscription

curl -X DELETE https://api.9squid.com/v1/api/webhooks/subscriptions/clxsub001 \
  -H "Authorization: Bearer <your_token>"

Response

{
  "success": true,
  "message": "Subscription removed"
}

Verifying Webhook Signatures

Every webhook delivery includes an X-9Squid-Signature header. Verify it using the secret returned when you created the subscription to confirm the request is genuine.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Always reject requests where the signature does not match.

Webhook Payload Shape

{
  "event": "deal.status_changed",
  "timestamp": "2026-04-15T11:00:00Z",
  "data": {
    "deal_id": "clx1a2b3c4d5e6f7g8h9",
    "previous_status": "IN_REVIEW",
    "current_status": "QC_COMPLETED"
  }
}

The data object shape varies by event type.

What’s Next

Create a Deal — subscribe before submitting a deal to receive live status updates
Run Selection Criteria — listen for sc.completed to know when results are ready
API Reference — Webhooks — full schema for all webhook endpoints

​Overview

​Step 1 — Create a Subscription

​Available Events

​Step 2 — List Your Subscriptions

​Step 3 — View Delivery History

​Step 4 — Replay a Failed Delivery

​Step 5 — Remove a Subscription

​Verifying Webhook Signatures

​Webhook Payload Shape

​What’s Next

Overview

Step 1 — Create a Subscription

Available Events

Step 2 — List Your Subscriptions

Step 3 — View Delivery History

Step 4 — Replay a Failed Delivery

Step 5 — Remove a Subscription

Verifying Webhook Signatures

Webhook Payload Shape

What’s Next