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

cURL

cURL

curl -X POST \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production",
  "url": "https://example.com/particle-webhooks"
}' \
  "https://api.particle.pro/v1/projects/{projectId}/webhooks/connections"

200

{
  "created_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "project_id": "<string>",
  "secret": "<string>",
  "secret_prefix": "<string>",
  "surface": "PLATFORM",
  "url": "<string>",
  "created_by": {
    "id": "<string>",
    "name": "<string>"
  },
  "name": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z"
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Headers

Idempotency-Key · string

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.

Required string length: 8 - 128

Path Parameters

projectId · string · required

Project ID (base62-encoded).

Body

application/json

url · string · required

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

Required string length: 1 - 2000

name · string

Optional human label for the connection.

Maximum string length: 200

Response

200

application/json

OK

created_at · string<date-time> · required

id · string · required

project_id · string · required

secret · string · 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_prefix · string · required

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

surface · enum<string> · 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.

Available options: PLATFORM, RADAR

url · string · required

Destination URL that signed POSTs are delivered to.

created_by · object

User who created the connection. Null when created via an API key.

Show child attributes

name · string

Optional human label for the connection.

revoked_at · string<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.