Webhooks

Webhooks let your integration react to events — a new data ingestion completing, a limit breaching, a custodian authority expiring — without polling. Every delivery is signed with a workspace-scoped key so you can verify authenticity before acting.

Events

  • Name
    calculated_data.created
    Type
    data
    Description

    A holdings / performance / transaction rebuild for a reporting entity has just finished. The payload includes the reporting entity ID and the cut-off date — fetch the relevant endpoints to pick up the new numbers.

  • Name
    limit.breached
    Type
    policy
    Description

    A limit that was previously within bounds just crossed its threshold. Payload includes the limit ID, the reporting entity, and the current and threshold values.

  • Name
    authority.expiring
    Type
    custodian
    Description

    A custodian authority is within its renewal window. Use to trigger a re-auth prompt in the client app before the feed breaks.

  • Name
    authority.revoked
    Type
    custodian
    Description

    An authority was revoked — either by the user, by Aleta after repeated upstream failures, or by the custodian directly.

  • Name
    api_version.published
    Type
    platform
    Description

    A new dated API cut is available. Useful for integrations that pin explicitly and want to plan their migration window.

Signing keys

Webhooks are signed with per-workspace keys. The keys rotate occasionally, and the verification endpoint exposes both the current and one-prior key so your verifier can accept a delivery mid-rotation.

Each delivery carries an Aleta-Signature header with a timestamp and an HMAC-SHA256 over the request body keyed with the current signing secret. Reject deliveries whose signature doesn't verify, or whose timestamp is more than five minutes off.

GET/v2/webhooks/keys

Fetch signing keys

Returns the two signing keys currently trusted for delivery verification — the active key and the most recently-retired one. Cache the response for the lifetime of your verifier; refetch when you see a signature that doesn't match either key.

Request

GET
/v2/webhooks/keys
curl https://api.aleta.io/v2/webhooks/keys \
  -H "Authorization: Bearer {token}"

Delivery semantics

  • At-least-once. Treat every event as potentially duplicated and dedupe on the event id.
  • Ordered per reporting entity. Events for a given reporting entity arrive in the order they occurred. Cross-entity ordering is not guaranteed.
  • Retries. Non-2xx responses trigger retries with exponential backoff for up to 24 hours. After that the delivery is dead-lettered and surfaced in the workspace's webhook diagnostics.

Return a 2xx response within 10 seconds. Slow handlers are treated as failures. Do the minimum work the delivery requires synchronously (dedupe + enqueue) and offload anything slow to a background job.

  • Authentication — how the bearer token for calling the webhook keys endpoint is issued.
  • Idempotency — the companion pattern for retrying mutating calls safely.