Webhooks

Nefesh can notify your server in real-time when a user's state changes. Instead of polling /v1/state, register a webhook URL and receive push notifications.

Event Types

Event	Triggered When
`state_change`	User transitions between states (e.g., Focused → Stressed)

Register a Webhook

curl -X POST https://api.nefesh.ai/webhooks/register   -H "X-Nefesh-Key: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://your-server.com/nefesh-webhook",
    "events": ["state_change"],
    "session_id": "sess_abc123"
  }'

Webhook Payload

{
  "event": "state_change",
  "session_id": "sess_abc123",
  "previous_state": "focused",
  "new_state": "stressed",
  "stress_score": 65,
  "timestamp": "2026-03-30T14:32:15Z"
}

Retry Policy

If your endpoint returns a non-2xx status code, Nefesh retries with exponential backoff:

1st retry: after 1 second
2nd retry: after 4 seconds
3rd retry: after 16 seconds

After 3 failed attempts, the webhook is marked as failed. You can view failed deliveries and retry them via the /webhooks/retries endpoint.

Security

Webhook payloads are signed with an HMAC-SHA256 signature in the X-Nefesh-Signature header. Verify the signature against your webhook secret to ensure the payload was sent by Nefesh.