Webhook Connections
tier:standard

Create a webhook connection

Creates a webhook connection (a destination URL plus a generated HMAC signing secret) that alerts can target as a WEBHOOK notification channel. The signing secret is returned only in this response — store it securely; it cannot be retrieved again. The URL must be https and must resolve to a public address. Send an Idempotency-Key to retry safely: a retry under the same key returns the same connection and secret instead of creating another.

post/v1/projects/{projectId}/webhooks/connections

Request

  • Base URL: https://api.particle.pro
  • URL: https://api.particle.pro/v1/projects/{projectId}/webhooks/connections
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

projectIdstring required

Project ID (base62-encoded).

Headers

Idempotency-Keystring

A key you choose, such as a UUID, to retry this request safely. Resend the same key with the same request and the first response is returned with Idempotent-Replayed: true instead of the request running again, for 24 hours after it succeeded. The same key with a different request returns 422 idempotency_key_reused; a retry while the first request is still running returns 409 idempotency_key_in_use. A request that fails does not use up its key.

Request body

namestring

Optional human label for the connection.

urlstring required

Destination URL. Must be https and resolve to a public address; private, loopback, and link-local addresses are rejected.

Response

OK

created_atstring date-time required
idstring required
namestring

Optional human label for the connection.

project_idstring required
revoked_atstring date-time

Set when the connection was deleted/revoked; absent for active connections. A revoked connection stops delivering and is skipped by alerts that still reference it.

secretstring required

Signing secret — shown only at create/rotate time. Store it securely; it cannot be retrieved again. Used to verify the X-Webhook-Signature header on delivered payloads.

secret_prefixstring required

Masked signing-secret prefix for identification. The full secret is shown only at create/rotate time and cannot be retrieved afterward.

surface'PLATFORM' | 'RADAR' required

Which Particle surface created this connection. Fixed at create time and inferred from the caller's authenticated surface context. Provenance only — an alert on either surface can deliver through it. Render it to show where the endpoint was registered.

urlstring required

Destination URL that signed POSTs are delivered to.

Changes

No recorded changes to this operation across all 2 revisions of this API.