Add a signing secret

POST/v1/webhook_endpoints/{endpoint}/secrets

Adds a second signing secret to an endpoint — the first half of a rotation.

Every ACTIVE secret signs every event, and all of the signatures ride the one webhook-signature header (space delimited). A verifier that accepts any one of them — which is what every Standard Webhooks library does — keeps working throughout. So the rotation is: add a secret here, deploy it to your receiver, confirm traffic is verifying against it, then retire the old one. No delivery is dropped at any point.

The signing set is read fresh for each delivery, immediately before it is sent. A delivery already on the wire when this call returns may therefore carry the previous set — the overlap is what makes that harmless, and it is why you deploy the new secret before retiring the old one rather than relying on an instant.

An endpoint may hold up to five ACTIVE secrets at once; past that the answer is HTTP 409 too_many_active_secrets. Every one of them signs every event, so the header grows with the count — a rotation needs two, and the rest of the room is for one you started and did not finish.

The new secret is shown exactly once, in this response.

Path ParametersExpand Collapse

endpoint: string

ReturnsExpand Collapse

SigningSecretCreated object { id, created_at, retired_at, 2 more }

A newly added signing secret, with its value — shown exactly once.

id: string

The secret’s id. Safe to log: it is a handle, not key material.

created_at: string

formatdate-time

retired_at: string

When this secret stopped signing. null while it is active.

formatdate-time

secret: string

The signing secret in presentation form (whsec_ + base64). Shown exactly once, here.

status: string

active or retired. Values grow additively.

Add a signing secret

curl https://whatsapp.messages.api.linqapp.com/v1/webhook_endpoints/$ENDPOINT/secrets \
    -X POST \
    -H "Authorization: Bearer $LINQ_WHATSAPP_API_KEY"

{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "retired_at": "2019-12-27T18:11:19.117Z",
  "secret": "secret",
  "status": "status"
}

Returns Examples

{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "retired_at": "2019-12-27T18:11:19.117Z",
  "secret": "secret",
  "status": "status"
}