> ## Documentation Index > Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt > Use this file to discover all available pages before exploring further. # Register webhook > Registers a destination URL for the authenticated project. The response contains a fresh `signingSecret` (64 lowercase hex characters) — **save it now**; it is returned only here and cannot be retrieved later. ### Delivery format Each event is delivered as an HTTP `POST` to your URL with these headers: | Header | Meaning | | --- | --- | | `X-Spectrum-Event` | Event type (e.g. `messages`). | | `X-Spectrum-Webhook-Id` | The id of this webhook, useful when you have multiple registered. | | `X-Spectrum-Timestamp` | UNIX epoch seconds at signing time. | | `X-Spectrum-Signature` | `v0=` — the signature you must verify (see below). | ### Verifying the signature Compute the HMAC-SHA256 of the string `v0:{X-Spectrum-Timestamp}:{rawBody}` keyed by your `signingSecret`, render it as lowercase hex, prefix with `v0=`, and compare in constant time against `X-Spectrum-Signature`. The signed input is the **exact request body bytes** — do not re-serialize the JSON before hashing. ``` sig = 'v0=' + hmacSha256Hex(signingSecret, 'v0:' + timestamp + ':' + rawBody) ``` For replay protection, also reject deliveries whose `X-Spectrum-Timestamp` differs from your current clock by more than ~5 minutes. ### Errors Returns `409` if an active webhook with the same URL is already registered for this project. Registering a URL that was previously deleted is allowed and yields a new webhook with a new signing secret. Requires `Authorization: Basic base64(projectId:projectSecret)`. ## OpenAPI ````yaml https://spectrum.photon.codes/openapi/json post /projects/{projectId}/webhooks/ openapi: 3.1.0 info: title: Spectrum Cloud External API description: Client-facing API for Spectrum Cloud. version: 1.0.0 servers: - url: https://spectrum.photon.codes security: [] tags: - name: billing description: Billing and subscription operations - name: imessage description: iMessage platform operations - name: lines description: Phone line enumeration across platforms - name: platforms description: Platform management operations - name: users description: User operations - name: voice description: Voice platform operations - name: webhooks description: Webhook registration for receiving Spectrum events - name: whatsapp-business description: WhatsApp Business platform operations - name: slack description: Slack platform operations paths: /projects/{projectId}/webhooks/: post: tags: - webhooks summary: Register webhook description: >- Registers a destination URL for the authenticated project. The response contains a fresh `signingSecret` (64 lowercase hex characters) — **save it now**; it is returned only here and cannot be retrieved later. ### Delivery format Each event is delivered as an HTTP `POST` to your URL with these headers: | Header | Meaning | | --- | --- | | `X-Spectrum-Event` | Event type (e.g. `messages`). | | `X-Spectrum-Webhook-Id` | The id of this webhook, useful when you have multiple registered. | | `X-Spectrum-Timestamp` | UNIX epoch seconds at signing time. | | `X-Spectrum-Signature` | `v0=` — the signature you must verify (see below). | ### Verifying the signature Compute the HMAC-SHA256 of the string `v0:{X-Spectrum-Timestamp}:{rawBody}` keyed by your `signingSecret`, render it as lowercase hex, prefix with `v0=`, and compare in constant time against `X-Spectrum-Signature`. The signed input is the **exact request body bytes** — do not re-serialize the JSON before hashing. ``` sig = 'v0=' + hmacSha256Hex(signingSecret, 'v0:' + timestamp + ':' + rawBody) ``` For replay protection, also reject deliveries whose `X-Spectrum-Timestamp` differs from your current clock by more than ~5 minutes. ### Errors Returns `409` if an active webhook with the same URL is already registered for this project. Registering a URL that was previously deleted is allowed and yields a new webhook with a new signing secret. Requires `Authorization: Basic base64(projectId:projectSecret)`. operationId: postProjectsByProjectIdWebhooks parameters: - name: projectId in: path required: true schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ requestBody: required: true content: application/json: schema: type: object properties: webhookUrl: type: string format: uri required: - webhookUrl additionalProperties: false application/x-www-form-urlencoded: schema: type: object properties: webhookUrl: type: string format: uri required: - webhookUrl additionalProperties: false multipart/form-data: schema: type: object properties: webhookUrl: type: string format: uri required: - webhookUrl additionalProperties: false responses: '200': description: Response for status 200 content: application/json: schema: type: object properties: succeed: type: boolean const: true data: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ webhookUrl: type: string format: uri createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ signingSecret: type: string required: - id - webhookUrl - createdAt - updatedAt - signingSecret additionalProperties: false required: - succeed - data additionalProperties: false ````