Skip to main content

Events & Webhooks API Reference

Subscribe to signed event notifications so partner systems react in real time instead of polling.

EventsReal-timev1.0.0OpenAPI 3.1

Publishes domain events (case status changes, new documents, application decisions) to subscriber endpoints. Each delivery is signed with HMAC-SHA256 (`X-IronBrick-Signature`), retried with exponential backoff, and available for replay for 7 days.

Reference design by Iron Brick LLC. Not an official government system; endpoints and data models are adapted to each agency's systems of record during implementation.

Base URLs
  • https://dev.ironbrick.us/sandbox/events/v1 Iron Brick sandbox (synthetic data; free developer account)
  • https://{agency-gateway}/events/v1 Agency deployment (behind the agency API gateway)

OpenAPI YAML JSON

Authentication

Send an OAuth 2.0 bearer token from POST https://dev.ironbrick.us/oauth/token in the Authorization header. Your application must hold the scope listed on each operation. How authentication works.

ScopeGrants
events:manageManage event subscriptions

POST /subscriptions

Create a subscription · requires scope events:manage

Request body application/json
json
{
  "eventTypes": [
    "case.status_changed"
  ],
  "callbackUrl": "https://partner.example.gov/hooks/ironbrick"
}
Responses
201Subscription created (includes the signing secret, shown once)
400Invalid request
401Missing or invalid access token
403Caller lacks the required scope
Example request
curl -X POST "https://dev.ironbrick.us/sandbox/events/v1/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"eventTypes": ["case.status_changed"], "callbackUrl": "https://partner.example.gov/hooks/ironbrick"}'
Response 201
{
  "subscriptionId": "SUB-0091",
  "eventTypes": [
    "case.status_changed",
    "document.available"
  ],
  "callbackUrl": "https://partner.example.gov/hooks/ironbrick",
  "status": "active",
  "createdAt": "2026-10-01T12:00:00Z"
}

GET /subscriptions

List subscriptions · requires scope events:manage

Responses
200Subscriptions
401Missing or invalid access token
403Caller lacks the required scope
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/events/v1/subscriptions" \
  -H "Authorization: Bearer $TOKEN"
Response 200
[
  {
    "subscriptionId": "SUB-0091",
    "eventTypes": [
      "case.status_changed",
      "document.available"
    ],
    "callbackUrl": "https://partner.example.gov/hooks/ironbrick",
    "status": "active",
    "createdAt": "2026-10-01T12:00:00Z"
  }
]

DELETE /subscriptions/{subscriptionId}

Delete a subscription · requires scope events:manage

Parameters
NameInTypeDescription
subscriptionId requiredpathstringSubscription identifier.
Responses
204Deleted
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
Example request
curl -X DELETE "https://dev.ironbrick.us/sandbox/events/v1/subscriptions/{subscriptionId}" \
  -H "Authorization: Bearer $TOKEN"

GET /event-types

List event types · requires scope events:manage

Responses
200Available event types
401Missing or invalid access token
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/events/v1/event-types" \
  -H "Authorization: Bearer $TOKEN"
Response 200
[
  {
    "type": "case.status_changed",
    "description": "A case moved to a new status."
  },
  {
    "type": "application.decided",
    "description": "An application was found eligible, ineligible, or awarded."
  },
  {
    "type": "document.available",
    "description": "A document passed scanning and is ready."
  },
  {
    "type": "request.released",
    "description": "A records request release package was published."
  }
]

POST /subscriptions/{subscriptionId}/replay

Replay recent events · requires scope events:manage

Re-delivers events from the last 7 days, for recovery after an outage.

Parameters
NameInTypeDescription
subscriptionId requiredpathstringSubscription identifier.
Request body application/json
json
{
  "since": "2026-10-01T00:00:00Z"
}
Responses
202Replay started
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
Example request
curl -X POST "https://dev.ironbrick.us/sandbox/events/v1/subscriptions/{subscriptionId}/replay" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"since": "2026-10-01T00:00:00Z"}'

Schemas

Subscription

FieldTypeDescription
subscriptionIdstring
eventTypesarray of string
callbackUrlstring (uri)
statusstring (active | paused | failing)
createdAtstring (date-time)