Alerts and Webhooks API: Real-Time Event Notifications

The Alerts endpoints let you programmatically create, list, and delete Smart Alert watchers for individuals you want to monitor. Webhooks take monitoring a step further: instead of polling, DocketStream pushes a structured event payload to your server the moment a monitored individual has activity — a new booking, a release, or a bond change. Together, alerts and webhooks eliminate polling latency and let you build truly real-time correctional intelligence workflows.

Both Alerts and Webhooks are Enterprise-only features. Ensure your account is on the Enterprise plan before configuring watchers or webhook endpoints. Contact support@docketstream.org to upgrade.

Alerts

POST /alerts — Create a Watcher

Register a new Smart Alert watcher. DocketStream will monitor all indexed counties (or a specific county) for activity matching the provided name and notify your webhook endpoint when a matching event occurs.

POST https://api.docketstream.org/v1/alerts
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "John Doe",
  "county": "clayton",
  "events": ["booking", "release", "bond_change"]
}

Body Parameters

string

required

The full name of the individual to watch. DocketStream performs fuzzy matching against this name across incoming booking records. Use the most complete name available (first and last) to minimize false positives.

string

Restrict monitoring to a specific county slug (e.g., "clayton", "fulton"). Omit this field to monitor all available counties.

array of strings

List of event types to receive notifications for. Accepted values: "booking", "release", "bond_change". Omit this field to subscribe to all three event types by default.

Response — 201 Created

{
  "id": "alert-abc123",
  "name": "John Doe",
  "county": "clayton",
  "events": ["booking", "release", "bond_change"],
  "created_at": "2024-06-10T14:32:00Z"
}

string

The unique identifier for this watcher. Use this ID to delete the watcher via DELETE /alerts/{id}.

string

The name configured for this watcher.

string | null

The county scope for this watcher, or null if monitoring all counties.

array of strings

The event types this watcher is subscribed to.

string

ISO 8601 timestamp of when the watcher was created.

GET /alerts — List All Watchers

Returns a paginated list of all active alert watchers on your account.

GET https://api.docketstream.org/v1/alerts
Authorization: Bearer YOUR_API_KEY

Response — 200 OK

{
  "total": 12,
  "limit": 50,
  "offset": 0,
  "alerts": [
    {
      "id": "alert-abc123",
      "name": "John Doe",
      "county": "clayton",
      "events": ["booking", "release", "bond_change"],
      "created_at": "2024-06-10T14:32:00Z"
    }
  ]
}

DELETE /alerts/ — Remove a Watcher

Delete an active alert watcher. Once deleted, DocketStream stops monitoring for the associated individual and no further webhook events are fired for that watcher.

DELETE https://api.docketstream.org/v1/alerts/alert-abc123
Authorization: Bearer YOUR_API_KEY

Path Parameter

string

required

The unique watcher ID returned when the alert was created (e.g., "alert-abc123").

Response — 204 No Content

A successful deletion returns HTTP 204 with an empty response body.

Webhooks

Register a Webhook Endpoint

Tell DocketStream where to send event payloads by registering a webhook URL. Your endpoint must be publicly accessible over HTTPS and able to accept POST requests.

POST https://api.docketstream.org/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://yourdomain.com/hook",
  "events": ["booking", "release", "bond_change"]
}

string

required

The publicly accessible HTTPS URL where DocketStream will POST event payloads. HTTP URLs are not accepted.

array of strings

required

Event types to deliver to this endpoint. Accepted values: "booking", "release", "bond_change". You can register multiple webhook endpoints with different event subsets.

Webhook Event Payload

When a monitored individual has matching activity, DocketStream sends a POST request to your registered URL with the following JSON body:

{
  "event": "booking",
  "alert_id": "alert-abc123",
  "timestamp": "2024-06-10T14:32:00Z",
  "record": {
    "id": "cltn-2024-00123",
    "name": "John Doe",
    "county": "Clayton",
    "booking_date": "2024-06-10T14:32:00Z",
    "charges": ["Theft by Taking"],
    "bond_amount": 5000
  }
}

string

The type of event that triggered this delivery: "booking", "release", or "bond_change".

string

The ID of the alert watcher that matched this activity.

string

ISO 8601 timestamp of when the event was detected by DocketStream.

object

A summary of the roster record associated with the event. For full record detail, pass record.id to GET /roster/{id}.

string

DocketStream roster record ID.

string

Individual’s name as recorded in the booking.

string

County where the event occurred.

string

ISO 8601 timestamp of the booking.

array of strings

Charges associated with the booking at the time of the event.

number | null

Bond amount in USD at the time of the event. For bond_change events, this reflects the new bond amount.

Responding to Webhooks

Your endpoint must return an HTTP 200 response within 5 seconds of receiving the request. If your server times out or returns a non-2xx status, DocketStream treats the delivery as failed and begins the retry sequence.

To keep response times under 5 seconds, acknowledge the webhook immediately and process the payload asynchronously using a background job or queue.

Retry Policy

DocketStream retries failed webhook deliveries up to 3 times using exponential backoff:

Attempt	Delay After Failure
1st retry	~30 seconds
2nd retry	~5 minutes
3rd retry	~30 minutes

If all three retries fail, the event is dropped and no further delivery attempts are made. Monitor your endpoint’s availability to avoid missing critical booking or release events.

Verifying Webhook Signatures

DocketStream signs every webhook delivery so you can verify that the request originated from DocketStream and that the payload has not been tampered with. Each request includes an X-DocketStream-Signature header containing an HMAC-SHA256 digest of the raw request body, computed using your webhook secret. You can find your webhook secret in Account Settings → API Keys after registering a webhook endpoint. Verify the signature in your handler before processing the payload:

import hmac
import hashlib

def verify_signature(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require("crypto");

function verifySignature(payloadBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payloadBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Always use a timing-safe comparison (e.g., hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js) when comparing HMAC digests. Standard string equality is vulnerable to timing attacks.

Reject any request where the signature does not match with an HTTP 401 response.

Overview

Endpoints

Alerts and Webhooks API: Real-Time Event Notifications

Alerts

POST /alerts — Create a Watcher

Body Parameters

Response — 201 Created

GET /alerts — List All Watchers

Response — 200 OK

DELETE /alerts/ — Remove a Watcher

Path Parameter

Response — 204 No Content

Webhooks

Register a Webhook Endpoint

Webhook Event Payload

Responding to Webhooks

Retry Policy

Verifying Webhook Signatures

​Alerts

​POST /alerts — Create a Watcher

​Body Parameters

​Response — 201 Created

​GET /alerts — List All Watchers

​Response — 200 OK

​DELETE /alerts/ — Remove a Watcher

​Path Parameter

​Response — 204 No Content

​Webhooks

​Register a Webhook Endpoint

​Webhook Event Payload

​Responding to Webhooks

​Retry Policy

​Verifying Webhook Signatures

Alerts

POST /alerts — Create a Watcher

Body Parameters

Response — 201 Created

GET /alerts — List All Watchers

Response — 200 OK

DELETE /alerts/ — Remove a Watcher

Path Parameter

Response — 204 No Content

Webhooks

Register a Webhook Endpoint

Webhook Event Payload

Responding to Webhooks

Retry Policy

Verifying Webhook Signatures