Webhook Configuration

Register a platform-wide endpoint

From the Platform Admin console:

Rotate, deactivate, or remove

Re-saving with a new secret value rotates the HMAC key. Leave the field blank to keep the current one. Use Deactivate to soft-pause event delivery — the row is preserved (URL, secret, events, history) and only isActive flips to false. Saving the form again (with URL + events) registers a fresh active webhook and flips isActive back to true — this is the only path back to active in the UI; no separate “Activate” button is exposed by design. The DELETE endpoint still exists for tooling/API consumers that want a hard removal.

Platform-level endpoints

# Create or update platform webhook
curl -X PUT https://mayaapi.teamcast.ai/api/v1/platform-admin/webhook-config \
  -H "Authorization: Bearer <PLATFORM_ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://api.acme.com/webhooks/teamcast",
    "events": [
      "interview.plan_generated",
      "interview.approved",
      "interview.rejected",
      "interview.assessment_pending"
    ]
  }'

Per-tenant endpoints (Platform Admin scope)

Platform Admin has two equivalent paths to manage a specific tenant's webhook: the dedicated /platform-admin/tenants/:tenantId/webhook-config route (recommended from a Platform Admin UI) and the shared /tenants/:id/webhook-config route (also used by Tenant Admins and Super Admins — see the Authorization section below for the caller-aware scoping rule).

# Configure webhook for one tenant under your platform
curl -X PUT https://mayaapi.teamcast.ai/api/v1/platform-admin/tenants/{tenantId}/webhook-config \
  -H "Authorization: Bearer <PLATFORM_ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://api.tenant.com/webhooks/teamcast",
    "events": [],
    "autoApprovePlans": false,
    "candidatePiiRetentionDays": 90,
    "assessmentRetentionDays": 365,
    "recordingRetentionDays": 30
  }'

# Send a test event (debugging)
curl -X POST https://mayaapi.teamcast.ai/api/v1/platform-admin/tenants/{tenantId}/webhook-test \
  -H "Authorization: Bearer <PLATFORM_ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "event": "interview.plan_generated" }'

Shared /tenants/:id/webhook-config route

The tenant self-serve route /api/v1/tenants/:id/webhook-config (GET / PUT / DELETE) is also callable by Platform Admin and Super Admin, with the same scoping rule applied to the URL :id:

Using a Platform Admin JWT against this shared route is equivalent to using the dedicated /platform-admin/tenants/:tenantId/webhook-config route — pick whichever fits your client. Cross-platform access is rejected with 403 Forbidden in both.

Quiet a webhook temporarily

For the platform-level webhook, click Deactivate in the Platform Admin console (or call PATCH /platform-admin/webhook-config/deactivate). For a tenant webhook, set isActive: false on the tenant config via the API. In both cases events still fire in Maya but no HTTP delivery is attempted. Useful during planned maintenance on the receiver side.

Subscribe to a subset of events

Pass a non-empty events array. Empty array (default) delivers all events. Valid values:

[
  "interview.info_needed",
  "interview.info_completed",
  "interview.plan_generated",
  "interview.approved",
  "interview.rejected",
  "interview.assessment_ready",
  "interview.assessment_pending",
  "interview.modification_requested",
  "interview.cancelled"
]

Rotate the HMAC secret

Supply a new secret (min 32 chars) in the upsert payload. The previous secret immediately stops verifying. Roll receivers in lock-step to avoid dropped deliveries — or run them side-by-side for a brief overlap window.