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
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"const res = await fetch("https://console.brevily.com/api/NORTHWIND/integrations/01JC6Y8QH2M4ZK7T9VRW3XNB5D/secret", { method: "PUT", headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, "Idempotency-Key": "4f9c1e2a-autumn", },});const answer = await res.json();Example answer
{ "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"}{ "code": "VALIDATION_FAILED", "message": "Check the form. (root): Not a value this field takes.", "details": { "fields": { "(root)": "Not a value this field takes." } }, "requestId": "18188559082372202519"}Made-up values. Send your own Idempotency-Key, one per change.
PathPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
ORG | string | required | Your organisation’s code. | 3 to 20 characters |
integration | string | required | — |
AnswerPermalink
IntegrationWithSecret
| Name | Type | Description | Allowed values |
|---|---|---|---|
id | string | The integration’s id. | — |
kind | string | A signed webhook, GA4 forwarding (Measurement Protocol), or an ad pixel the links that name it fire in the visitor’s browser. | WEBHOOK, GA4, PIXEL |
url | string | A webhook’s https address; null for every other kind. | or null |
measurementId | string | A GA4 stream’s measurement id; null for every other kind. | or null |
platform | string | An ad pixel’s ad network; null for every other kind. | META, LINKEDIN, X, GOOGLE_ADS, MICROSOFT_ADS, PINTEREST; or null |
pixelId | string | An ad pixel’s id at its ad network (Google Ads: its conversion id, AW-…); null for every other kind. | or null |
linkId | string | The one link it sends; null for every link (and for a pixel, which the links that name it fire). | or null |
folder | string | The 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 |
events | string[] | 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 |
status | string | DISABLED queues nothing; turning one off gives up what it still owed. | ACTIVE, DISABLED |
activeSince | date-time | Clicks from then on are sent (when it was made or last turned on). | or null |
sent | integer | Deliveries sent this billing period. | — |
failed | integer | Deliveries given up this billing period. | — |
lastSentOn | date-time | Its last delivery sent this billing period; null for none. | or null |
createdOn | date-time | When it was made. | — |
secret | string | A 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
| 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.
Type a call, a field or a guide.