nexalwarenexalwaredocs
API ReferenceWebhooks

Register a webhook

Dashboard-only

This mirrors what a human does from the Nexalware web app - it's not meant to be automated by a third-party integration, even though a session token from Log in can technically call it. If you're building an integration that controls devices, use an API key instead: have an Owner/Admin grant it access to a device (a DeviceGrant), and use the Device Control endpoints.
POST
/api/v1/webhooks

Delivers every event type (relay_changed, telemetry, device_online/offline, schedule_fired) to url, scoped to whatever keyId already has a DeviceGrant for - no separate scope to configure. keyId is not a secret - it's the same value List your account's API keys returns for each key (e.g. key_9f8e7d6c), not the key's raw secret value. No key yet? Create an API key first, then grant it device access before a webhook on it will deliver anything - see Create a Scoped Device Grant. See Receiving Webhooks for how to receive and verify what gets delivered here. The signing secret is returned once, at creation only, and cannot be recovered afterward - rotate it with POST /:webhookId/rotate-secret if it's lost.

Authorization

sessionAuth
AuthorizationBearer <token>

A session token for an existing account, obtained from POST /auth/login (see the Authentication endpoints) - not an API key. Endpoints marked with this scheme reject API key callers outright, regardless of what that key is granted. Outside the Authentication endpoints themselves, everything requiring this scheme manages dashboard resources (schedules, rules, grants, keys, device configuration) and mirrors what a human does in the Nexalware web app - it is not meant to be automated by a third-party integration the way the Device Control endpoints are.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "keyId": "string",    "url": "http://example.com"  }'
{  "webhookId": "string",  "keyId": "string",  "url": "string",  "secret": "string"}

Read a webhook's recent delivery attempts GET

The last 50 attempts, newest first - each event fires its own delivery row per attempt, so a retried delivery shows up multiple times with increasing `attempt`.

Rotate a webhook's signing secret POST

The previous secret stops verifying signatures immediately - update your endpoint's verification key before or right after calling this.