Webhooks - Alpha Documentation

Create Webhook

POST /v1/webhooks

Request Body

{
  "url": "https://your-app.com/alpha-webhook",
  "events": ["rating.changed", "rating.downgrade", "signal.critical"],
  "tickers": ["AAPL", "MSFT", "GOOGL"],
  "secret": "your-webhook-secret"
}

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint to receive events
`events`	string[]	Yes	Event types to subscribe to
`tickers`	string[]	No	Filter to specific companies (omit for all)
`secret`	string	No	Used to sign webhook payloads for verification

Event Types

Event	Trigger
`rating.changed`	Any rating grade or score change
`rating.upgrade`	Grade improved (e.g., BB to BBB)
`rating.downgrade`	Grade decreased (e.g., A to BBB)
`rating.watch`	Watch status changed (positive/negative)
`signal.critical`	T1 or T2 signal detected
`signal.new`	Any new signal detected

Response

{
  "id": "wh_abc123",
  "url": "https://your-app.com/alpha-webhook",
  "events": ["rating.changed", "rating.downgrade", "signal.critical"],
  "tickers": ["AAPL", "MSFT", "GOOGL"],
  "status": "active",
  "created_at": "2026-04-04T12:00:00Z"
}

Webhook Payload

When an event fires, Alpha sends a POST request to your URL:

{
  "event": "rating.downgrade",
  "timestamp": "2026-04-04T14:30:00Z",
  "data": {
    "ticker": "META",
    "company_name": "Meta Platforms Inc.",
    "previous_grade": "BBB",
    "current_grade": "BB",
    "previous_score": 71.2,
    "current_score": 64.8,
    "trajectory": "Declining",
    "trigger_signal": {
      "id": "sig_xyz789",
      "type": "regulatory_action",
      "title": "EU AI Act Article 6 non-compliance finding"
    }
  }
}

Signature Verification

If you provided a secret, each webhook includes a signature header:

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

Verify by computing HMAC-SHA256 of the raw body with your secret:

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

List Webhooks

GET /v1/webhooks

Returns all active webhooks for your API key.

Delete Webhook

DELETE /v1/webhooks/{id}

Deactivates and removes a webhook subscription.

Retry Policy

Failed deliveries (non-2xx response) are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook is marked as failing and you receive an email notification.

​Create Webhook

​Request Body

​Event Types

​Response

​Webhook Payload

​Signature Verification

​List Webhooks

​Delete Webhook

​Retry Policy