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
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" }'const res = await fetch("https://console.brevily.com/api/NORTHWIND/integrations", { method: "POST", headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, "Idempotency-Key": "4f9c1e2a-autumn", "Content-Type": "application/json", }, body: JSON.stringify({ "kind": "WEBHOOK", "url": "https://www.example.com/sale/autumn", "events": [ "link.click" ], "measurementId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D", "apiSecret": "example", "platform": "META", "pixelId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D", "link": "example", "folder": "example" }),});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. kind: Not a value this field takes.", "details": { "fields": { "kind": "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 |
BodyPermalink
JSON. An unknown field is refused with a 400 naming it.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
kind | string | optional | WEBHOOK when left out. | WEBHOOK, GA4, PIXEL |
url | string | optional | A webhook’s https address. | — |
events | string[] | optional | The events a webhook receives; link.click when left out. | link.click, link.created, link.updated, link.expired, link.broken, event.reported |
measurementId | string | optional | GA4: the stream’s measurement id. | — |
apiSecret | string | optional | GA4: the stream’s Measurement Protocol secret. | — |
platform | string | optional | A pixel’s ad network. | META, LINKEDIN, X, GOOGLE_ADS, MICROSOFT_ADS, PINTEREST |
pixelId | string | optional | A pixel’s id at its ad network. | — |
link | string | optional | Send one link only, as domain/back-half; not with folder, and not for a pixel. | — |
folder | string | optional | Send one folder’s links only, by its code; not with link, and not for a pixel. | — |
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 · 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.