Skip to main content

​
How alerts reach you

Pylva can deliver alerts through webhook, email, and Slack channels. Builders configure webhook destinations in the dashboard, attach alert channels to rules, verify signed webhook payloads with the SDK helper, and monitor failed deliveries through the dead-letter queue. Rule events are the history of what happened. Alerts are notifications delivered to your configured channels.

​
What can trigger an alert

Alerts can come from:
  • Rules and controls (cost thresholds, budget limits).
  • Anomalies and margin risk.
  • Instrumentation health checks (silence, cost drops).
  • Billing and payment events (invoices, payment failures, disputes).
Email and Slack are useful for humans; webhooks are useful for systems that need to route, page, or automate follow-up.

​
Webhook setup

Configure webhook destinations in the dashboard under Settings -> Webhooks. Webhook configs define:
  • Destination URL.
  • Event types to deliver.
  • Enabled or disabled state.
  • Signing secret.
Webhook secrets are shown once. Save them in your receiver’s secret store. Rule alert channels attach webhook, email, or Slack delivery to a specific rule. A webhook config by itself does not mean every rule will notify that destination.

​
Webhook payload

Every delivery is a JSON envelope with a stable shape; data varies by event type:
Event types include cost.threshold_exceeded, budget.exceeded, margin.alert, anomaly.detected, instrumentation.health, instrumentation.silence, instrumentation.cost_drop, billing.invoice_created, billing.payment_failed, and billing.dispute_created. Receivers should ignore unknown types so new event types can ship without breaking you.

​
Verify webhook requests

Webhook delivery uses signed requests. Verify the raw body with X-Pylva-Signature, X-Pylva-Timestamp, and the signing secret shown when the webhook is created or rotated.

​
Signature scheme

  • The signature is HMAC-SHA256 over the string {timestamp}.{raw_body} - the timestamp, a period, then the exact raw request body.
  • X-Pylva-Timestamp is epoch seconds as an integer string.
  • X-Pylva-Signature is the 64-character hex digest, optionally prefixed sha256=.
  • Reject requests whose timestamp is more than 300 seconds from your clock (replay protection), and compare signatures with a timing-safe comparison.
  • Both SDK helpers implement all of this; signWebhook / sign_webhook are available for testing your receiver.

​
TypeScript

​
Python

Reject the request if verification fails. Use the raw request body, not a parsed and re-serialized JSON object.

​
Retries and DLQ

Pylva retries transient delivery failures. If delivery still fails, the alert is held in the dead-letter queue for review. Use the DLQ to inspect failed deliveries, fix the receiver or channel configuration, and retry. Owners can retry DLQ entries. Handled or no-longer-needed entries can be dismissed.

​
Practical checklist

  • Create webhook configs before attaching webhook channels to rules.
  • Store webhook signing secrets immediately.
  • Verify signatures in the receiver before acting on an alert.
  • Use email or Slack for human review.
  • Use webhooks for routing, paging, and automation.
  • Review the DLQ when expected alerts do not arrive.