Integrations › Roll a webhook’s signing secret

Integrations

Roll a webhook’s signing secret

PUT/api/{ORG}/integrations/{integration}/secretPermalink

Answers the IntegrationWithSecret.

Permission
Integrations · edit
Plan
Plans that include the API: Pricing
Retry
Safe with an Idempotency-Key

Example request

bash
curl -X PUT "https://console.brevily.com/api/NORTHWIND/integrations/01JC6Y8QH2M4ZK7T9VRW3XNB5D/secret" \  -H "x-api-key: brv_ak_7Fq2Lw9xK3" \  -H "x-api-secret: $BREVILY_SECRET" \  -H "Idempotency-Key: 4f9c1e2a-autumn"

Example answer

json
{  "id": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",  "kind": "WEBHOOK",  "url": "https://www.example.com/sale/autumn",  "measurementId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",  "platform": "META",  "pixelId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",  "linkId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",  "folder": "example",  "events": [    "link.click"  ],  "status": "ACTIVE",  "activeSince": "2026-11-05T09:41:00Z",  "sent": 1,  "failed": 0,  "lastSentOn": "2026-11-05T09:41:00Z",  "createdOn": "2026-11-05T09:41:00Z",  "secret": "example"}

Made-up values. Send your own Idempotency-Key, one per change.

PathPermalink

Path parameters
NameTypeRequiredDescriptionAllowed values
ORGstringrequiredYour organisation’s code.3 to 20 characters
integrationstringrequired—

AnswerPermalink

IntegrationWithSecret

Answer fields
NameTypeDescriptionAllowed values
idstringThe integration’s id.—
kindstringA signed webhook, GA4 forwarding (Measurement Protocol), or an ad pixel the links that name it fire in the visitor’s browser.WEBHOOK, GA4, PIXEL
urlstringA webhook’s https address; null for every other kind.or null
measurementIdstringA GA4 stream’s measurement id; null for every other kind.or null
platformstringAn ad pixel’s ad network; null for every other kind.META, LINKEDIN, X, GOOGLE_ADS, MICROSOFT_ADS, PINTEREST; or null
pixelIdstringAn ad pixel’s id at its ad network (Google Ads: its conversion id, AW-…); null for every other kind.or null
linkIdstringThe one link it sends; null for every link (and for a pixel, which the links that name it fire).or null
folderstringThe code of the one folder it sends the links of (those in it now: a link moved out stops matching, one moved in starts); null for every link or one link.or null
eventsstring[]What it receives: a webhook’s choice (link.click when none was chosen), GA4’s link.click alone, a pixel’s nothing.link.click, link.created, link.updated, link.expired, link.broken, event.reported
statusstringDISABLED queues nothing; turning one off gives up what it still owed.ACTIVE, DISABLED
activeSincedate-timeClicks from then on are sent (when it was made or last turned on).or null
sentintegerDeliveries sent this billing period.—
failedintegerDeliveries given up this billing period.—
lastSentOndate-timeIts last delivery sent this billing period; null for none.or null
createdOndate-timeWhen it was made.—
secretstringA webhook’s signing secret (whsec_…), shown on this answer only: keep it to verify X-Brevily-Signature. Null for every other kind.or null

ErrorsPermalink

Errors
Status Code When
400 VALIDATION_FAILED A field, a parameter or the body is wrong; details.fields says which.
400 IDEMPOTENCY_KEY_INVALID The Idempotency-Key is longer than 255 characters.
401 UNAUTHENTICATED No key, a key that does not match, or one expired or revoked.
403 ACCESS_DENIED The key lacks Integrations · edit, or the organisation’s plan does not include it.
404 NOT_FOUND No organisation with that code for this key, or no such record in it.
409 CONFLICT
409 IDEMPOTENCY_IN_FLIGHT The first call with this Idempotency-Key is still running.
413 PAYLOAD_TOO_LARGE
415 UNSUPPORTED_MEDIA
422 IDEMPOTENCY_MISMATCH The same Idempotency-Key was sent with a different request.
429 RATE_LIMITED Too many calls: wait Retry-After seconds.

Rate limitsPermalink

Counted with every other call of the organisation, by plan: Pricing. The answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; more on rate limits.