Webhookovi

Styrar webhookovi šalju potpisane HTTP obavijesti kada se resursi u vašem radnom prostoru promijene. Koristite ih za sinkronizaciju poveznica i klikova s CRM-om, pokretanje automatizacija u vašem sustavu ili slanje funnel događaja u skladište podataka.

Ovo zamjenjuje ukinuti API webhookova samo za poveznice (/v1/link-webhooks). Nove integracije trebaju koristiti samo /v1/webhooks/*.

Postavljanje webhooka

Slijedite ove korake da od nule dođete do provjerenog, produkcijski spremnog krajnjeg endpointa.

1. Pripremite URL svog prijemnika

Vaš poslužitelj treba javno HTTPS URL koji prihvaća POST zahtjeve s JSON tijelom. U produkciji, povratni URL-ovi moraju koristiti HTTPS.

Vaš handler treba:

• Pročitati sirovo tijelo zahtjeva kao string ili buffer (ne parsirajte JSON prije provjere potpisa).
• Pročitati zaglavlja Styrar-Signature, Styrar-Event-Id i Styrar-Event-Type.
• Provjeriti potpis (pogledajte odjeljak Provjera potpisa ispod).
• Vratiti 2xx brzo nakon što je događaj prihvaćen. Stavite teži posao u red asinkrono.

Primjer putanje: https://your-app.com/webhooks/styrar

Styrar ne može isporučiti na privatne ili loopback adrese poput localhost.

2. Dobijte API pristup (za programsko postavljanje)

Ako stvarate endpointe putem API-ja umjesto nadzorne ploče, potreban vam je Bearer token sa:

Stvorite API ključ u Postavke → API ključevi sa webhooks:read i webhooks:write, ili koristite OAuth pristupni token iz povezane aplikacije s istim opsezima.

Za poslovne radne prostore, proslijedite companyId u zahtjevima za popis i stvaranje.

3. Stvorite endpoint u nadzornoj ploči

1. Prijavite se i otvorite Postavke → Webhookovi (/settings/webhooks).
2. Pod Endpointi, unesite svoj URL endpointa (javni HTTPS povratni adresa).
3. Opcionalno dodajte Opis (na primjer "Produkcijska CRM sinkronizacija").
4. Odaberite Događaje koje želite (potreban je najmanje jedan). Česti izbori:
   • link.clicked za praćenje klikova
   • link.created / link.updated / link.deleted za životni ciklus poveznice
   • post.published i campaign.created za funnel događaje
5. Kliknite Dodaj endpoint.

Nakon stvaranja, Styrar prikazuje vašu tajnu za potpisivanje (whsec_live_… ili whsec_test_…). Odmah je kopirajte i pohranite u svoj upravitelj tajni. Prikazuje se samo jednom. Ako je izgubite, koristite Rotiraj tajnu na endpointu i ažurirajte svoj poslužitelj.

4. Stvorite endpoint putem API-ja

Authorization: Bearer sty_live_your_api_key
Content-Type: application/json

{
  "companyId": "cmxyz_company",
  "url": "https://your-app.com/webhooks/styrar",
  "description": "Production CRM sync",
  "eventTypes": [
    "link.clicked",
    "link.created"
  ]
}

{
  "id": "wh_ep_abc123",
  "url": "https://your-app.com/webhooks/styrar",
  "description": "Production CRM sync",
  "enabled": true,
  "eventTypes": [
    "link.clicked",
    "link.created"
  ],
  "secretPrefix": "whsec_l",
  "companyId": "cmxyz_company",
  "userId": null,
  "disabledAt": null,
  "createdAt": "2026-06-22T12:00:00.000Z",
  "updatedAt": "2026-06-22T12:00:00.000Z",
  "secret": "whsec_live_abc123onlyShownOnce"
}

Pohranite secret odmah. Ne vraća se u kasnijim GET zahtjevima. Prazan niz eventTypes pretplaćuje na sve vrste događaja; nadzorna ploča zahtijeva najmanje jedan eksplicitni događaj.

5. Pošaljite testni događaj

Potvrdite da je vaš poslužitelj dostupan prije nego što se oslonite na uživo promet.

Nadzorna ploča: Na retku endpointa kliknite Pošalji test. Styrar isporučuje webhook.test događaj. Trebali biste vidjeti uspješnu obavijest s HTTP statusnim kodom.

API:

Authorization: Bearer sty_live_your_api_key

{
  "ok": true,
  "statusCode": 200
}

Kada test uspije, vaš poslužitelj bi trebao primiti webhook.test događaj (pogledajte Primanje događaja na vašem poslužitelju ispod).

Provjerite Nedavne isporuke u nadzornoj ploči (ili GET /v1/webhooks/deliveries) ako test ne uspije. Česti problemi:

6. Provjerite i obradite isporuke

Na svaki POST na vaš URL:

1. Parsirajte Styrar-Signature u vremensku oznaku t i digest v1.
2. Odbacite ako je t starije od vaše tolerancije (preporučeno 5 minuta).
3. Izračunajte HMAC-SHA256 od "{t}.{raw_body}" s tajnom vašeg endpointa.
4. Usporedite s v1 koristeći usporedbu konstantnog vremena.
5. Parsirajte JSON tek nakon uspješne provjere.
6. Deduplicirajte na temelju Styrar-Event-Id (isporuka najmanje jednom).

Pogledajte odjeljak Provjera potpisa ispod za primjer u Node.js-u.

7. Idite uživo

• Držite endpoint Omogućenim u nadzornoj ploči.
• Pretplatite se samo na događaje koje trebate (smanjuje šum i trošak).
• Pratite Nedavne isporuke za neuspjehe i koristite Ponovi kad je potrebno.
• Rotirajte tajnu ako je mogla biti otkrivena (Rotiraj tajnu u nadzornoj ploči ili POST …/rotate-secret).

Brzi početak

1. Dobijte API pristup sa webhooks:read i webhooks:write opsezima (API ključ ili OAuth).
2. Izložite javni HTTPS prijemnik i stvorite endpoint u Postavke → Webhookovi ili putem POST /v1/webhooks/endpoints.
3. Kopirajte tajnu za potpisivanje kad se prikaže i sigurno je pohranite.
4. Pošaljite testni događaj i potvrdite da vaš poslužitelj provjerava Styrar-Signature i vraća 2xx.
5. Obradite uživo događaje s deduplikacijom na Styrar-Event-Id.

Autentikacija

Upravljanje webhookovima zahtijeva Bearer token s opsezima navedenim u koraku 2 iznad. API ključevi s podudarajućim opsezima funkcioniraju jednako kao OAuth pristupni tokeni.

Vrste događaja

Pozovite GET /v1/webhooks/event-types za uživo katalog u vašem okruženju. Pretplatite se na određene vrste po endpointu, ili proslijedite prazan niz eventTypes za primanje svih događaja.

webhook.test se šalje samo kada kliknete Pošalji test; ne emitira se uobičajenom aktivnošću radnog prostora.

Omotnica događaja

Svaka isporuka koristi isti oblik najviše razine. Polja specifična za događaj nalaze se pod data.object:

Cjeloviti primjer isporuke (omotnica + teret link.created):

{
  "id": "evt_outbox_abc123",
  "type": "link.created",
  "api_version": "2026-06-22",
  "created_at": "2026-06-22T12:00:00.000Z",
  "workspace": {
    "type": "company",
    "company_id": "cmxyz_company"
  },
  "data": {
    "object": {
      "id": "clink_abc123",
      "short_code": "summer",
      "title": "Summer sale",
      "original_url": "https://example.com/sale",
      "is_active": true,
      "company_id": "cmxyz_company",
      "campaign_id": "ccamp_abc",
      "link_group_id": null,
      "created_at": "2026-06-22T12:00:00.000Z"
    }
  }
}

Za osobne radne prostore, workspace.type je personal a workspace.company_id je null. Teret može sadržavati company_id: null na objektima poveznica.

Sažetak događaja

link.created

Okida se kada se nova kratka poveznica spremi u vaš radni prostor.

Česte upotrebe: Sinkronizirajte nove poveznice s CRM-om, pokrenite automatizacije dobrodošlice, ili indeksirajte poveznice u eksternom pretraživačkom skladištu.

Polja data.object:

{
  "id": "clink_abc123",
  "short_code": "summer",
  "title": "Summer sale",
  "original_url": "https://example.com/sale",
  "is_active": true,
  "company_id": "cmxyz_company",
  "campaign_id": "ccamp_abc",
  "link_group_id": null,
  "created_at": "2026-06-22T12:00:00.000Z"
}

link.updated

Okida se kada se postojeća kratka poveznica izmijeni (odredište, naslov, oznake, mapa, UTM postavke, itd.).

Česte upotrebe: Održavajte eksterne sustave sinkroniziranima kad se poveznica promijeni bez ponovnog stvaranja.

Polja data.object: Isto kao link.created (vidi iznad).

{
  "id": "clink_abc123",
  "short_code": "summer",
  "title": "Summer sale (updated)",
  "original_url": "https://example.com/sale-v2",
  "is_active": true,
  "company_id": "cmxyz_company",
  "campaign_id": "ccamp_abc",
  "link_group_id": "lgrp_promos",
  "created_at": "2026-06-22T12:00:00.000Z"
}

link.deleted

Okida se kada je kratka poveznica mekano izbrisana (isActive postavljeno na false). Poveznica prestaje javno razrješavati ali ostaje u povijesti vašeg radnog prostora.

Česte upotrebe: Uklonite poveznice iz eksternih katalogа ili pauzirajte automatizacije vezane za taj kratki kod.

Polja data.object: Isti oblik kao link.created, s is_active uvijek false.

{
  "id": "clink_abc123",
  "short_code": "summer",
  "title": "Summer sale",
  "original_url": "https://example.com/sale",
  "is_active": false,
  "company_id": "cmxyz_company",
  "campaign_id": "ccamp_abc",
  "link_group_id": null,
  "created_at": "2026-06-22T12:00:00.000Z"
}

link.clicked

Okida se nakon što se klik posjetitelja pohrani. Isporučuje se asinkrono (ne na putu preusmjeravanja), pa očekujte malu odgodu pri opterećenju.

Česte upotrebe: Analitika klikova u stvarnom vremenu, geo-temeljeno usmjeravanje u vašem sustavu, CRM feedovi aktivnosti, ili unos u skladište podataka.

Privatnost: Tereti uključuju geo i uređajne dimenzije, ne sirove IP adrese.

Polja data.object:

{
  "id": "clink_abc123",
  "link_id": "clink_abc123",
  "short_code": "summer",
  "title": "Summer sale",
  "country": "NL",
  "city": "Amsterdam",
  "device": "mobile",
  "browser": "Chrome",
  "os": "iOS",
  "platform": null,
  "referrer": "https://instagram.com/",
  "routing_rule_id": null,
  "experiment_variant_id": null,
  "clicked_at": "2026-06-22T12:00:00.000Z"
}

link.experiment.completed

Okida se kada je A/B test na kratkoj poveznici označen kao dovršen i odabrana je pobjednička varijanta.

Česte upotrebe: Bilježite rezultate eksperimenata, ažurirajte nadzorne ploče, ili pokrenite naknadne kampanje temeljene na pobjedniku.

Polja data.object:

Svaka stavka u variants:

{
  "id": "lexp_abc123",
  "link_id": "clink_abc123",
  "short_code": "summer",
  "status": "completed",
  "assignment_mode": "weighted",
  "winning_variant_id": "lvar_b",
  "ended_at": "2026-06-22T14:00:00.000Z",
  "variants": [
    {
      "id": "lvar_a",
      "label": "Control",
      "weight": 50,
      "destination_url": "https://example.com/a",
      "clicks": 120
    },
    {
      "id": "lvar_b",
      "label": "Variant B",
      "weight": 50,
      "destination_url": "https://example.com/b",
      "clicks": 184
    }
  ]
}

campaign.created

Okida se kada je nova kampanja stvorena u vašem radnom prostoru.

Česte upotrebe: Postavite mape kampanja u eksternim alatima, pokrenite tijekove pripisivanja, ili obavijestite voditelje računa.

Polja data.object:

{
  "id": "ccamp_abc123",
  "name": "Summer launch",
  "description": "Q2 product push",
  "company_id": "cmxyz_company",
  "user_id": null,
  "brand_id": "cbrand_abc",
  "created_at": "2026-06-22T12:00:00.000Z"
}

post.published

Okida se kada se zakazana ili trenutna objava uspješno objavi na svim konfiguriranim platformskim ciljevima.

Česte upotrebe: Obavijestite niže sustave da je sadržaj uživo, zatvorite krug na automatizacijama kampanja, ili sinkronizirajte stanje objave u skladište podataka.

Napomena: Emitira se samo kada svaki cilj uspije. Djelomični neuspjesi danas ne emitiraju ovaj događaj.

Polja data.object:

{
  "id": "cpost_abc123",
  "post_id": "cpost_abc123",
  "status": "PUBLISHED",
  "company_id": "cmxyz_company",
  "user_id": null,
  "brand_id": "cbrand_abc",
  "campaign_id": "ccamp_abc123",
  "published_at": "2026-06-22T12:00:00.000Z",
  "platform_count": 3
}

webhook.test

Sintetički ping poslan samo kad kliknete Pošalji test u nadzornoj ploči ili pozovete POST /v1/webhooks/endpoints/:id/test.

Česte upotrebe: Provjerite svoj URL prijemnika, TLS, provjeru potpisa i rukovanje odgovorom prije nego što idete uživo.

Polja data.object:

{
  "endpoint_id": "wh_ep_abc123",
  "message": "Styrar webhook test ping"
}

Primjeri API-ja

Popis endpointa

Authorization: Bearer sty_live_your_api_key

[
  {
    "id": "wh_ep_abc123",
    "url": "https://your-app.com/webhooks/styrar",
    "description": "Production CRM sync",
    "enabled": true,
    "eventTypes": ["link.clicked", "link.created"],
    "secretPrefix": "whsec_l",
    "companyId": "cmxyz_company",
    "userId": null,
    "disabledAt": null,
    "createdAt": "2026-06-22T12:00:00.000Z",
    "updatedAt": "2026-06-22T12:00:00.000Z"
  }
]

Primanje događaja na vašem poslužitelju

Kada se pretplaćeni događaj okine, Styrar šalje POST na URL vašeg endpointa. Ovo je teret koji vaš handler prima:

Content-Type: application/json
Styrar-Event-Id: evt_outbox_abc123
Styrar-Event-Type: link.clicked
Styrar-Signature: t=1719052800,v1=8f4b2c1a9e0d3f7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3
User-Agent: Styrar-Webhooks/1.0

{
  "id": "evt_outbox_abc123",
  "type": "link.clicked",
  "api_version": "2026-06-22",
  "created_at": "2026-06-22T12:00:00.000Z",
  "workspace": {
    "type": "company",
    "company_id": "cmxyz_company"
  },
  "data": {
    "object": {
      "id": "clink_abc123",
      "link_id": "clink_abc123",
      "short_code": "summer",
      "title": "Summer sale",
      "country": "NL",
      "city": "Amsterdam",
      "device": "mobile",
      "browser": "Chrome",
      "os": "iOS",
      "referrer": "https://instagram.com/",
      "routing_rule_id": null,
      "experiment_variant_id": null,
      "clicked_at": "2026-06-22T12:00:00.000Z"
    }
  }
}

{
  "received": true
}

Tijelo vašeg odgovora može biti prazno. Vratite bilo koji 2xx status nakon što provjerite potpis i prihvatite događaj. Styrar ponovno pokušava na ne-2xx odgovorima.

Teret testnog pinga

Radnja Pošalji test isporučuje webhook.test s manjim teretom:

Content-Type: application/json
Styrar-Event-Id: evt_test_abc123
Styrar-Event-Type: webhook.test
Styrar-Signature: t=1719052800,v1=...

{
  "id": "evt_test_abc123",
  "type": "webhook.test",
  "api_version": "2026-06-22",
  "created_at": "2026-06-22T12:00:00.000Z",
  "workspace": {
    "type": "company",
    "company_id": "cmxyz_company"
  },
  "data": {
    "object": {
      "endpoint_id": "wh_ep_abc123",
      "message": "Styrar webhook test ping"
    }
  }
}

Popis nedavnih isporuka

Authorization: Bearer sty_live_your_api_key

[
  {
    "id": "wh_del_abc123",
    "endpointId": "wh_ep_abc123",
    "outboxEventId": "wh_out_abc123",
    "eventType": "link.clicked",
    "status": "delivered",
    "attemptCount": 1,
    "lastStatusCode": 200,
    "lastError": null,
    "durationMs": 142,
    "nextAttemptAt": null,
    "deliveredAt": "2026-06-22T12:00:01.000Z",
    "createdAt": "2026-06-22T12:00:00.500Z"
  }
]

Upravljanje endpointima

GET    /v1/webhooks/endpoints?companyId={id}
POST   /v1/webhooks/endpoints
GET    /v1/webhooks/endpoints/:id
PATCH  /v1/webhooks/endpoints/:id
DELETE /v1/webhooks/endpoints/:id
POST   /v1/webhooks/endpoints/:id/test
POST   /v1/webhooks/endpoints/:id/rotate-secret

Tajna za potpisivanje (whsec_live_… / whsec_test_…) vraća se točno jednom prilikom stvaranja i na rotate-secret. Možete registrirati do 25 endpointa po opsegu radnog prostora.

Isporuke

GET  /v1/webhooks/deliveries?endpointId={id}
GET  /v1/webhooks/deliveries/:id
POST /v1/webhooks/deliveries/:id/retry

Svaki redak isporuke prati status, attemptCount, nextAttemptAt, lastStatusCode, lastError i deliveredAt. Pregledajte neuspjehe u nadzornoj ploči pod Postavke → Webhookovi ili ponovite putem API-ja.

Format isporuke

Svaki uživo događaj je HTTP POST na vaš povratni URL. Zaglavlja i tijelo prikazani su u Primanje događaja na vašem poslužitelju iznad.

Polja omotnice:

Tereti klikova uključuju geo i uređajne dimenzije, ne sirove IP adrese.

Provjera potpisa

Potpis slijedi shemu u stilu Stripea. Potpisuje "{timestamp}.{raw_body}" koristeći HMAC-SHA256 s tajnom vašeg endpointa.

1. Parsirajte Styrar-Signature u t (unix vremenska oznaka) i v1 (hex digest).
2. Odbacite ako je t izvan vaše tolerancije (preporučujemo 5 minuta).
3. Izračunajte očekivani digest i usporedite s v1 koristeći usporedbu konstantnog vremena.

import crypto from 'node:crypto'

function verifyStyrarWebhook(secret, signatureHeader, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((part) => part.trim().split('=')),
  )

  const timestamp = Number(parts.t)
  const receivedDigest = parts.v1 || ''

  if (!Number.isFinite(timestamp)) return false
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false

  const expectedDigest = crypto
    .createHmac('sha256', secret)
    .update(\`${timestamp}.${rawBody}\`)
    .digest('hex')

  try {
    return crypto.timingSafeEqual(
      Buffer.from(expectedDigest, 'utf8'),
      Buffer.from(receivedDigest, 'utf8'),
    )
  } catch {
    return false
  }
}

Uvijek provjerite naspram sirovog tijela zahtjeva prije parsiranja JSON-a.

Pouzdanost

• Isporuke su najmanje jednom. Deduplicirajte koristeći Styrar-Event-Id ili id omotnice.
• Neuspjele isporuke ponovno se pokušavaju s eksponencijalnim odgađanjem do uspjeha ili maksimalnog broja pokušaja.
• Ako vaš poslužitelj vrati HTTP 410, Styrar automatski onesposobljuje endpoint.
• Odgovorite sa 2xx odmah nakon što prihvatite događaj; obradite teži posao asinkrono.

Ograničenja

• HTTPS je obavezan u produkciji za povratne URL-ove.
• 25 endpointa po osobnom ili poslovnom opsegu radnog prostora.
• Tajne za potpisivanje prikazuju se jednom prilikom stvaranja i rotacije; pohranite ih u svoj upravitelj tajni.

Povezano

• Konverzijski piksel - pratite konverzije na odredišnim stranicama koje ne kontrolirate
• Kratke poveznice i QR u centru za pomoć
• API ključevi i povezane aplikacije