— Section / Developers LIVE · v1

Webhooks.

Subscribe to real-time events. Signed payloads. Automatic retries. Full delivery logs.

Developer Documentation

Webhooks

Receive real-time notifications when alert conditions are met. Webhooks push event data to your server as HTTP POST requests with signed payloads for security.

Overview

Webhooks allow your application to receive real-time notifications when alert conditions are triggered. Instead of polling the API, Evens pushes event data directly to an endpoint you specify.

Webhook delivery works alongside the alert system:

You create a webhook endpoint in your account settings
When creating an alert rule, select "Webhook" as a delivery channel
Optionally pick which specific endpoint to target (defaults to your first active endpoint)
When the alert triggers, Evens sends a signed POST request to your endpoint

Premium feature

Webhooks require an active Premium subscription and the alerts feature to be enabled.

Setup

1. Register a webhook endpoint

Go to Account → Webhooks and add your endpoint URL. The URL must be publicly accessible via HTTPS (HTTP allowed in development).

Each endpoint receives a unique signing secret upon creation. Store this securely — you'll need it to verify webhook signatures.

2. Create an alert with webhook delivery

When creating or editing an alert, enable the Webhook channel and optionally select which endpoint to use. If you have multiple endpoints, you can assign different alerts to different endpoints.

3. Respond with 2xx

Your endpoint should respond with a 200-299 status code within 10 seconds. Non-2xx responses or timeouts are recorded as failures.

Event Types

Event	Description	Alert Type
`alert.triggered`	An alert rule's conditions have been met	All types
`alert.price_target`	Price field crossed a target threshold	price_target
`alert.arbitrage`	Arbitrage ROI exceeded the configured minimum	arbitrage_threshold
`alert.price_change`	Price moved by the configured percentage in a time window	price_change

Payload Format

All webhook events are sent as POST requests with a JSON body:

POST https://your-server.com/webhooks/evens

Headers

Content-Type: application/json

X-Evens-Signature: sha256=<hex_digest>

User-Agent: Evens-Webhooks/1.0

"event":          "alert.triggered",
"notification_id": 42,
"alert_rule_id":   7,
"title":           "Price Target Hit: BTC > 0.65",
"body":            "Yes Ask on 'Will BTC hit $100k?' is now 0.68, above your target of 0.65",
"snapshot": {
  "field":    "yes_ask",
  "value":    0.68,
  "operator": "gt",
  "target":   0.65
},
"triggered_at":    "2026-03-14T10:30:00Z"

Payload fields

Field	Type	Description
event	string	Event type identifier
notification_id	integer	Unique ID of this notification
alert_rule_id	integer	ID of the alert rule that triggered
title	string	Human-readable alert title
body	string	Detailed description of the triggered condition
snapshot	object	Point-in-time data that caused the trigger (varies by alert type)
triggered_at	string	ISO 8601 timestamp of when the alert fired

Snapshot by alert type

price_target

{
  "field": "yes_ask",
  "value": 0.68,
  "operator": "gt",
  "target": 0.65
}

arbitrage_threshold

{
  "best_roi": 8.5,
  "min_roi": 5.0,
  "combination": [...]
}

price_change

{
  "field": "yes_ask",
  "current": 0.72,
  "previous": 0.60,
  "change_pct": 20.0
}

Signature Verification

Every webhook request includes an X-Evens-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your endpoint's secret.

Always verify signatures before processing webhook payloads to ensure the request genuinely came from Evens and hasn't been tampered with.

rb Ruby

js Node.js

py Python

Delivery & Retries

10s

Connection timeout

Maximum retry attempts

Consecutive failures before auto-disable

Delivery attempts follow these rules:

Successful delivery requires a 2xx response within 10 seconds
Failed deliveries are retried up to 3 times with exponential backoff
After 10 consecutive failures across any deliveries, the endpoint is automatically disabled
Disabled endpoints can be re-enabled from your account settings
During quiet hours, webhook deliveries are queued and sent when quiet hours end

Testing

Several approaches for testing webhooks during development:

Local development

Use a tunneling service to expose your local server:

Admin Webhook Tester

Admins can use the Webhook Tester in the admin panel to register endpoints and send test events. This lets you verify your endpoint is working without waiting for a real alert to fire.

Simple receiver

A minimal endpoint for debugging webhook payloads:

Best Practices

Verify signatures

Always validate the X-Evens-Signature header to confirm authenticity.

Respond quickly

Return a 2xx response immediately. Process webhook data asynchronously in a background job.

Handle duplicates

Use notification_id for idempotency. Retries may deliver the same event multiple times.

Use HTTPS

Always use HTTPS endpoints in production. The signing secret is transmitted during registration only.