API 2026-11-01 Draft contract. Webhook payloads are final for this version; the REST API is in design and not live yet.

Webhooks

HOACraft POSTs one JSON event to your HTTPS endpoint each time something happens in the field. Reply 2xx within 10 seconds; anything else is retried for up to 24 hours with the same event id. See the integration guide for verification code in Node and C#.

The request

Every delivery has the same headers. The signature is the hex HMAC-SHA256 of "<t>.<raw body>", keyed with the endpoint's signing secret. The sample below is signed with whsec_example_do_not_use_in_production.

POST /integrations/hoacraft/webhook HTTP/1.1
Host: pm.example.com
Content-Type: application/json
User-Agent: HOACraft-Webhooks/1.0
HOACraft-Event: violation.created
HOACraft-Delivery: evt-ho4l8rev40-6
HOACraft-Signature: t=1794585600,v1=ddeb3b3f4bfc6115c61ef9a213ceb24f4c28266c1f51357fca64211217f1339e

{"id":"evt-ho4l8rev40-6","type":"violation.created","api_version":"2026-11-01","created_at":"2026-11-13T16:00:00.000Z…

Events

Every event uses the same envelope: id, type, api_version, created_at, community and data. The samples are real output from the HOACraft app, checked against the code on every build.

EventWhenTopic
violation.createdA violation was approved in the fieldViolations
violation.still_openA re-check after the cure date found the violation unfixedViolations
violation.resolvedA re-check found the violation fixedViolations
work_order.createdA work order was submitted in the fieldWork orders
work_order.updatedA work order changed status or vendorWork orders
work_order.completedA work order was marked completedWork orders
acc_request.site_reviewedAn inspector recorded an ACC site review (a recommendation, not a decision)ACC requests
acc_request.decidedA manager recorded the committee decision in HOACraftACC requests
drive.completedAn inspector ended a driveDrives
webhook.testConnectivity checkSetup
EVENTwebhook.test

Connectivity check

data fields

messagestring

Sample payload

{
  "id": "evt-ho4l8rev40-p",
  "type": "webhook.test",
  "api_version": "2026-11-01",
  "created_at": "2026-11-13T16:00:00.000Z",
  "community": {
    "id": "willow-creek",
    "name": "Willow Creek Estates"
  },
  "data": {
    "message": "Hello from HOACraft. Your endpoint is reachable."
  }
}

Managing endpoints

Manage webhook endpoints and replay events.

List endpoints

GET/webhook-endpoints

Responses

200OKarray of WebhookEndpoint

Example request

curl -X GET "https://sandbox.api.hoacraft.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY"
Example response
[
  {
    "id": "string",
    "url": "https://pm.example.com/integrations/hoacraft/webhook",
    "events": [
      "violation.created"
    ],
    "enabled": true,
    "created_at": "2026-11-13T16:00:00Z"
  }
]

Register an endpoint

POST/webhook-endpoints

The signing secret is returned once, in this response.

Request body

urlrequiredstring (uri) matches ^https://
eventsarray of EventTypeOmit for all event types.

Responses

201Createdobject

Example request

curl -X POST "https://sandbox.api.hoacraft.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://pm.example.com/integrations/hoacraft/webhook",
  "events": [
    "violation.created"
  ]
}'
Example response
{
  "id": "string",
  "url": "https://pm.example.com/integrations/hoacraft/webhook",
  "events": [
    "violation.created"
  ],
  "enabled": true,
  "created_at": "2026-11-13T16:00:00Z",
  "secret": "whsec_…"
}

Rotate the signing secret

POST/webhook-endpoints/{endpointId}/rotate-secret

The old secret keeps working for 24 hours so you can deploy the new one.

Parameters

endpointIdrequiredpath · string

Responses

200New secretobject

Example request

curl -X POST "https://sandbox.api.hoacraft.com/v1/webhook-endpoints/we_8f2k1/rotate-secret" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY"
Example response
{
  "secret": "string"
}

Send a webhook.test event

POST/webhook-endpoints/{endpointId}/test

Parameters

endpointIdrequiredpath · string

Responses

202Queued

Example request

curl -X POST "https://sandbox.api.hoacraft.com/v1/webhook-endpoints/we_8f2k1/test" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY"

List or replay recent events (30 days)

GET/events

Parameters

typequery · EventType
sincequery · string (date-time)
delivery_statusquery · string
One of: delivered failed pending
cursorquery · string

Responses

200Events, same envelopes as the webhook bodies.object

Example request

curl -X GET "https://sandbox.api.hoacraft.com/v1/events" \
  -H "Authorization: Bearer $HOACRAFT_API_KEY"
Example response
{
  "data": [
    {
      "id": "evt-ho4l8rev40-p",
      "type": "webhook.test",
      "api_version": "2026-11-01",
      "created_at": "2026-11-13T16:00:00.000Z",
      "community": {
        "id": "willow-creek",
        "name": "Willow Creek Estates"
      },
      "data": {
        "message": "Hello from HOACraft. Your endpoint is reachable."
      }
    }
  ],
  "next_cursor": "string"
}

Signature tester

Runs in your browser; nothing is sent anywhere. Use Sign to make a correctly signed request for your receiver, and Verify to check a request you captured.