Webhooks

When grading completes, CHCK notifies your backend by POSTing JSON to URLs you register. Delivery is handled by the CHCK grading pipeline (Rails); registration is via the Partner API or dashboard data store.

Register targets

Use the Partner API to manage webhook URLs for your user:

Method	Path	Purpose
GET	/v1/webhook-targets	List registered URLs
POST	/v1/webhook-targets	Add a URL
DELETE	/v1/webhook-targets/{id}	Remove a URL

Create request

{
  "outcome": "success",
  "url": "https://partner.example.com/hooks/grading-success"
}

outcome must be "success" or "failure". Register separate URLs if you want different handlers.

List response (snake_case)

{
  "webhook_targets": [
    {
      "id": 1,
      "outcome": "success",
      "url": "https://partner.example.com/hooks/grading-success",
      "created_at": "2026-05-24T12:00:00.000Z"
    }
  ]
}

POST create response

POST /v1/webhook-targets returns the created row with camelCase fields (userId, createdAt, …) from the ORM layer. Only the list endpoint uses snake_case.

Inbound payload

CHCK POSTs to your URL with:

{
  "grading_session_id": "d4882286-cfd3-4bde-9ee3-b1d1de1b9922",
  "outcome": "success"
}

Field	Type	Description
grading_session_id	UUID string	Pass to GET /v1/gradings/{id}
outcome	"success" | "failure"	Which target URL was invoked

Your handler responsibilities

1. Respond with HTTP 2xx (200, 201, 204, etc.) promptly.
2. On non-2xx responses, CHCK retries until a success status is received.
3. Fetch full results asynchronously if needed:

curl -H "Authorization: Bearer shbx_..." \
  "https://api.chck.ai/v1/gradings/${GRADING_SESSION_ID}"

Idempotency

The same session may be retried on delivery failures. Design handlers to be idempotent (e.g. upsert by grading_session_id).

Security

• Use HTTPS endpoints only in production.
• Verify requests if CHCK provides signing headers in your contract (not part of the open Partner API spec today).
• Do not expose internal-only URLs without authentication at the network edge.

Legacy Rails rake tasks

Older integrations used Rails rake tasks (grading_webhooks:add_success_target, etc.). New partners should use POST /v1/webhook-targets instead.