---
title: "Create a webhook connection"
method: POST
path: "/v1/projects/{projectId}/webhooks/connections"
tags: ["Webhook Connections", "tier:standard"]
---

# Create a webhook connection

`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

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.

## Path parameters

- `projectId` string, required: Project ID (base62-encoded).

## Headers

- `Idempotency-Key` string

## Request body

- CreateWebhookConnectionBody
  - `name` string: Optional human label for the connection.
  - `url` string, required: Destination URL. Must be https and resolve to a public address; private, loopback, and link-local addresses are rejected.

## Response `200`

OK

- WebhookConnectionCreated
  - `created_at` string, date-time, required
  - `created_by` Creator
    - `id` string, required: Creator's user ID
    - `name` string, required: Creator's display name
  - `id` string, required
  - `name` string: Optional human label for the connection.
  - `project_id` string, required
  - `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.
  - `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` '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.
  - `url` string, required: Destination URL that signed POSTs are delivered to.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)