Webhooks & Alerts Overview

Subscribe to PipAI events delivered as signed HTTPS POSTs to your endpoint. Use webhooks to react to strategy events, alerts, and account state changes without polling.

This module covers:

• Registering and managing webhook subscriptions.
• The payload format and event types.
• Verifying signatures so you can trust the sender.

Delivery semantics

Webhook deliveries are at-least-once. PipAI guarantees that every event will be delivered to a healthy endpoint at least one time, but the same event may arrive more than once during retries or transient failures.

A delivery is considered successful when your endpoint returns a 2xx HTTP status within 10 seconds of receiving the request. Any other outcome — non-2xx response, TLS error, connection refused, or timeout — schedules a retry.

Retries follow a fixed exponential backoff schedule:

Attempt	Delay after previous attempt
2	1 second
3	5 seconds
4	30 seconds
5	2 minutes
6	10 minutes
7	30 minutes
8	2 hours
9	6 hours
10	24 hours

After 24 hours from the original event time, PipAI gives up and the event is permanently dropped from the queue for that webhook.

Concurrency

Deliveries to a given webhook are not strictly ordered. PipAI dispatches events concurrently to maximise throughput, and retries can re-order events relative to their original creation time.

If your handler depends on order — for example, processing strategy.position_opened before the matching strategy.position_closed — use the per-event ordering hints embedded in the data payload (e.g. opened_at, closed_at, or a seq field where present). Do not rely on the order of arrival.

Note that not every event type carries a seq. When ordering matters and no seq is present, sort by the event's created_at timestamp combined with related entity IDs.

Idempotency

Because delivery is at-least-once, your handler must be idempotent. The recommended pattern is:

1. Read the id field from the event body (or the X-PipAI-Event-Id header — they are identical).
2. Look it up in a short-lived cache or database table with a 24-hour TTL.
3. If already seen, respond 200 OK immediately and skip processing.
4. Otherwise, process the event and record the id before returning 200 OK.

A 24-hour deduplication window is more than sufficient — PipAI never retries beyond that horizon.

TLS

Webhook target URLs must use https://. Plain http:// URLs are rejected at registration time with 400 INVALID_PARAMETER.

The TLS certificate presented by your endpoint must chain to a publicly trusted root. Self-signed certificates, expired certificates, and certificates with hostname mismatches are rejected at delivery time and counted as failures.

Status auto-pause

Each webhook tracks a consecutive_failures counter. The counter increments on every failed delivery (after all 10 attempts have been exhausted) and resets to 0 on the next successful delivery.

When consecutive_failures reaches 50, the webhook automatically transitions to broken status and deliveries stop. The webhook will not receive new events until it is manually re-enabled — either via the (forthcoming) PATCH endpoint or by a successful call to Test Webhook, which clears the counter on a 2xx response.

This guard prevents PipAI from hammering an endpoint that is permanently down and prevents queues from growing unboundedly.