Back to Blog

Real-Time Webhook Notifications for Threat Events

Polling is dead. Today we're shipping webhook notifications — real-time push notifications that fire whenever a threat is added to or revoked from the SATIS blockchain.

Why Webhooks

If you're integrating SATIS into your security operations, you probably want to know immediately when a new critical threat appears or when a false positive gets revoked. Previously, you'd need to poll the threats API or connect to our SSE stream. Webhooks give you a simpler option: tell us where to send events, and we'll POST them to your endpoint as they happen.

Setting Up a Webhook

Create a webhook subscription through the API:

curl -X POST "https://setecastronomyinc.com/api/v1/webhooks" \
     -H "Cookie: tcs_session=your_session" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-server.com/satis-webhook",
       "events": "threat.added,threat.revoked"
     }'

You'll receive a response with your webhook_id and a secret for signature verification. Save the secret — it's shown only once.

Event Payload

When a threat event occurs, SATIS sends a POST request to your URL:

{
  "event": "threat.added",
  "timestamp": "2026-02-28T18:30:00+00:00",
  "data": {
    "threat_id": "TC-8A3F92B1...",
    "target": "203.0.113.45",
    "severity": "critical",
    "action": "block",
    "source": "fail2ban",
    "confidence": 92,
    "txid": "abc123..."
  }
}

Security: HMAC Signatures

Every webhook delivery includes an X-SATIS-Signature header containing an HMAC-SHA256 signature of the payload body, computed using your webhook secret:

X-SATIS-Signature: sha256=5d3a1c...

Verify this in your handler to confirm the request genuinely came from SATIS:

import hmac, hashlib

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

Reliability

Webhook deliveries have a 5-second timeout. If your endpoint returns a non-2xx status code or times out, SATIS records the failure and retries on subsequent events. After 10 consecutive failures, the webhook is automatically disabled to prevent wasting resources on dead endpoints.

You can monitor delivery status via the webhooks list endpoint and re-enable disabled webhooks by deleting and recreating them.

Supported Events

Event	Description
threat.added	A new threat was published to the blockchain
threat.revoked	An existing threat was revoked

Managing Webhooks

# List your webhooks
curl "https://setecastronomyinc.com/api/v1/webhooks" \
     -H "Cookie: tcs_session=your_session"

# Delete a webhook
curl -X DELETE "https://setecastronomyinc.com/api/v1/webhooks/wh_abc123" \
     -H "Cookie: tcs_session=your_session"

Webhooks are available on all plans. Configure them in the Customer Portal or via the API.

---

Back to Blog