Integrations › Add an integration

Integrations

Add an integration

POST/api/{ORG}/integrationsPermalink

Adds a webhook (kind WEBHOOK, url, and optionally events: which of link.click, link.created, link.updated, link.expired, link.broken and event.reported it receives — clicks when left out) or GA4 forwarding (kind GA4, measurementId, apiSecret), for every link, one link (link, as domain/back-half) or one folder (folder, its code: the links in it as they come and go, on a plan with folder webhooks; one for every link is for people who see every folder), or an ad pixel (kind PIXEL, platform, pixelId), which the links that name it fire. Every kind counts against the plan’s integrations. Answers 201 with the webhook’s signing secret, shown this once.

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

Example request

bash
curl -X POST "https://console.brevily.com/api/NORTHWIND/integrations" \  -H "x-api-key: brv_ak_7Fq2Lw9xK3" \  -H "x-api-secret: $BREVILY_SECRET" \  -H "Idempotency-Key: 4f9c1e2a-autumn" \  -H "Content-Type: application/json" \  -d '{    "kind": "WEBHOOK",    "url": "https://www.example.com/sale/autumn",    "events": [      "link.click"    ],    "measurementId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",    "apiSecret": "example",    "platform": "META",    "pixelId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",    "link": "example",    "folder": "example"  }'

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

BodyPermalink

JSON. An unknown field is refused with a 400 naming it.

Body fields
NameTypeRequiredDescriptionAllowed values
kindstringoptionalWEBHOOK when left out.WEBHOOK, GA4, PIXEL
urlstringoptionalA webhook’s https address.—
eventsstring[]optionalThe events a webhook receives; link.click when left out.link.click, link.created, link.updated, link.expired, link.broken, event.reported
measurementIdstringoptionalGA4: the stream’s measurement id.—
apiSecretstringoptionalGA4: the stream’s Measurement Protocol secret.—
platformstringoptionalA pixel’s ad network.META, LINKEDIN, X, GOOGLE_ADS, MICROSOFT_ADS, PINTEREST
pixelIdstringoptionalA pixel’s id at its ad network.—
linkstringoptionalSend one link only, as domain/back-half; not with folder, and not for a pixel.—
folderstringoptionalSend one folder’s links only, by its code; not with link, and not for a pixel.—

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 · create, 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.