Webhooks

Aleta follows the Standard Webhooks specification for propagating system events to external users.

An asymmetric signing scheme based on elliptic curve cryptography allows webhook consumers to verify the integrity of payloads originating from Aleta. The key type is P256, and public keys for verification are exposed as JSON Web Keys at GET /api/v2/webhooks/keys.

Each delivery carries the webhook-id, webhook-timestamp and webhook-signature headers. The signed content is {webhook-id}.{webhook-timestamp}.{body} (UTF-8). The signature is ES256 (ECDSA over P-256 with SHA-256) in raw r||s form (64 bytes), Base64-encoded and prefixed with v1a,. The webhook-timestamp header is the delivery attempt time in Unix seconds; the timestamp field in the body is the time of the event.

Events

Following Standard Webhooks, JSON payloads always contain the following fields:

typestringRequired: Determines the type of event that occurred.
timestampstringRequired: The point in time at which the event occurred.
dataobjectRequired: Data describing the event itself (depends on the event type).

The following subsections describe the various events emitted from the system.

Calculated data created

clientIdstringRequired: Identifier of the client for which data is ready.

Example

JSON

{
  "type": "calculated_data.created",
  "timestamp": "2024-10-17T07:05:18Z",
  "data": {
    "clientId": "6710efbc34673a0a646a45de"
  }
}

GET/api/v2/webhooks/keys

Fetch signing keys

Get the active public key for verifying webhook payload integrity. The keys array holds the current key. kid is a hex SHA-256 value identifying the key version. x and y are padded standard Base64, not the base64url encoding JSON Web Keys normally use.

Request

GET/api/v2/webhooks/keys

curl https://api.aleta.ai/api/v2/webhooks/keys \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

Response: 200 OK

{
  "keys": [
    {
      "kid": "98abecd03c00eb1d4fc7ed50c1286cafd80d1eb3d93603fe449e96d4291a76f5",
      "kty": "EC",
      "crv": "P-256",
      "x": "mgWOHCsiFfz8ejgVH/aMsvnIz4jQrKUYLVZ5ppu3sgo=",
      "y": "sbtaHcMfp3YXRo6syjv581qRJJ2KyCHXaF1m3PIVzEg="
    }
  ]
}