# Webhooks

> A signed request at your own URL each time one of your cases changes state: the payload, the signature check and the retry schedule.

Source: https://evictionsapi.com/docs/webhooks

## Register an endpoint

Register an https URL with `POST /v1/webhook-endpoints`. An endpoint belongs to the mode of the key that registered it: one registered with a test key receives events for test cases only. The response has the endpoint’s `id` and its signing `secret` (`whsec_...`), which no later request returns.

```sh
curl -X POST https://api.evictionsapi.com/v1/webhook-endpoints \
  -H "Authorization: Bearer eak_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/evictions" }'
```

## The event

Each delivery is a `POST` with a JSON body and two headers. The payload carries no tenant data: only identifiers, the event name and the case’s state.

```http
POST /webhooks/evictions HTTP/1.1
Content-Type: application/json
X-Evictions-Timestamp: 1791152169
X-Evictions-Signature: 9f2c5e0a...  (64 lowercase hex characters)
```

```json
{
  "id": "evt_fe8bc3a6-fd3a-4199-bb5a-1ef652b5cbac",
  "type": "case.submit",
  "caseId": "case_e2d1a3fa-830d-42e1-acb3-58922df3393b",
  "state": "submitted",
  "createdAt": "2026-10-04T22:16:09.280Z"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The event’s id. The same event has the same id on every delivery attempt, so use it to ignore one you have already handled. |
| `type` | string | case. followed by the name of the event, such as case.submit. The names are listed below. |
| `caseId` | string | The case the event belongs to. Fetch it with GET /v1/cases/{id}. |
| `state` | string | The case’s state after the event. For an event that does not change the state, its current state. |
| `createdAt` | string | When the event happened, as an ISO 8601 UTC time. |

Event types for a state transition: `case.submit`, `case.assign_attorney`, `case.auto_prepare`, `case.begin_review`, `case.request_changes`, `case.approve_notice`, `case.send_notice`, `case.notice_served`, `case.start_cure_period`, `case.cure`, `case.close_resolved`, `case.cure_period_expired`, `case.approve_filing`, `case.submit_filing`, `case.filing_rejected`, `case.rework_filing`, `case.filing_accepted`, `case.send_summons`, `case.summons_served`, `case.schedule_hearing`, `case.record_judgment`, `case.request_writ`, `case.writ_issued`, `case.close`, `case.withdraw`, `case.hold`, `case.resume`, `case.retry_unstarted`.

Recorded without a state change: `case.cure_reported`, `case.service_failed`.

## Verify the signature

`X-Evictions-Timestamp` is the time of the delivery, in whole seconds since the Unix epoch. `X-Evictions-Signature` is the lowercase hex of an HMAC-SHA256 of `${timestamp}.${body}`, keyed with the endpoint’s secret: the timestamp, a dot, then the request body exactly as it arrived. Use the raw body, compare in constant time, and refuse a delivery whose timestamp is more than a few minutes from your clock.

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 300;

// secret:  the whsec_... value returned once when you registered the endpoint
// rawBody: the request body exactly as received (a string or Buffer), before any JSON parsing
// headers: the request headers (Node lowercases the names)
export function verifyEvictionsWebhook(secret, rawBody, headers) {
  const timestamp = headers['x-evictions-timestamp'];
  const signature = headers['x-evictions-signature'];
  if (typeof timestamp !== 'string' || typeof signature !== 'string') return false;

  // Refuse old deliveries, so a captured request cannot be replayed later.
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!(ageSeconds <= TOLERANCE_SECONDS)) return false;

  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const given = Buffer.from(signature);
  const wanted = Buffer.from(expected);
  return given.length === wanted.length && timingSafeEqual(given, wanted);
}

```

```js
import { createServer } from 'node:http';
import { verifyEvictionsWebhook } from './verify.js';

const SECRET = process.env.EVICTIONS_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks).toString('utf8');
    if (req.method !== 'POST' || !verifyEvictionsWebhook(SECRET, rawBody, req.headers)) {
      res.writeHead(400).end();
      return;
    }
    const event = JSON.parse(rawBody);
    // Answer with a 2xx straight away and do the work afterwards.
    // The same event.id can arrive more than once, so ignore one you have already handled.
    res.writeHead(200).end();
    console.log(event.type, event.caseId, event.state);
  });
}).listen(3000);

```

## Responses and retries

Answer with any 2xx status within 10 seconds and the delivery counts as done. Anything else counts as a failure. A failed delivery is tried up to five tries in all:

| Try | When |
| --- | --- |
| 1 | Straight away, when the event happens. |
| 2 | 1 minute after the first try failed. |
| 3 | 5 minutes after the second. |
| 4 | 30 minutes after the third. |
| 5 | 120 minutes after the fourth. If this one fails too, the delivery is given up. |

Treat deliveries as at least once, and do not assume they arrive in order: dedupe on `id`, and read the case with `GET /v1/cases/{id}` when the order matters.
