Quickstart

ProposedNot yet callable

This documents a design under review. Endpoints, payloads and field names may change before release.

Register an endpoint

Endpoints are registered per institution from the dashboard, or by API for teams automating environment setup.

POST /v1/webhook_endpoints
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "url": "https://erp.your-college.edu/hooks/onetap",
  "events": ["attendance.recorded", "attendance.updated"],
  "description": "Production ERP sync"
}

Subscribe only to what you handle. Every event you accept and ignore is load on your server and noise in your logs.

Store the secret

The response carries the signing secret. It is shown once.

{
  "id": "whe_8f21c0",
  "url": "https://erp.your-college.edu/hooks/onetap",
  "events": ["attendance.recorded", "attendance.updated"],
  "secret": "whsec_9c2f...",
  "status": "enabled",
  "created_at": "2026-07-19T09:15:22Z"
}

Store secret somewhere your application can read at runtime. Onetap cannot show it again — you would have to roll it.

Receive your first event

Trigger a test delivery from the dashboard, or have a student tap a device. A correct handler does three things in order:

1. Read the raw request body (before any JSON parsing)
2. Verify the X-Onetap-Signature header
3. Enqueue the work and return 2xx immediately

Steps 1 and 2 are covered in Authentication. Step 3 matters because deliveries time out after 10 seconds — acknowledge first, process after.