Webhook

I webhook di Styrar inviano notifiche HTTP firmate quando le risorse nel tuo workspace cambiano. Usali per sincronizzare link e click con un CRM, attivare automazioni nel tuo stack o trasmettere gli eventi del funnel a un data warehouse.

Questo sostituisce la vecchia API webhook solo per i link (/v1/link-webhooks), ora ritirata. Le nuove integrazioni dovrebbero usare solo /v1/webhooks/*.

Configurare un webhook

Segui questi passaggi per arrivare da zero a un endpoint verificato e pronto per la produzione.

1. Prepara l'URL del tuo receiver

Il tuo server ha bisogno di un URL HTTPS pubblico che accetti richieste POST con un body JSON. In produzione, gli URL di callback devono usare HTTPS.

Il tuo handler dovrebbe:

• Leggere il body grezzo della richiesta come stringa o buffer (non fare il parsing del JSON prima di verificare la firma).
• Leggere gli header Styrar-Signature, Styrar-Event-Id e Styrar-Event-Type.
• Verificare la firma (vedi la sezione Verifica delle firme più sotto).
• Restituire 2xx rapidamente dopo che l'evento è stato accettato. Accoda il lavoro pesante in modo asincrono.

Esempio di percorso: https://your-app.com/webhooks/styrar

Styrar non può consegnare ad indirizzi privati o loopback come localhost.

2. Ottieni l'accesso API (per la configurazione via codice)

Se crei gli endpoint tramite l'API invece della dashboard, ti serve un token Bearer con:

Crea una API key in Impostazioni → API keys con webhooks:read e webhooks:write, oppure usa un access token OAuth di un'app collegata con gli stessi scope.

Per i workspace aziendali, passa companyId nelle richieste di elenco e creazione.

3. Crea un endpoint nella dashboard

1. Accedi e apri Impostazioni → Webhook (/settings/webhooks).
2. In Endpoint, inserisci il tuo URL endpoint (il callback HTTPS pubblico).
3. Aggiungi opzionalmente una Descrizione (ad esempio "Sincronizzazione CRM di produzione").
4. Seleziona gli Eventi che desideri (ne è richiesto almeno uno). Scelte comuni:
   • link.clicked per il tracciamento dei click
   • link.created / link.updated / link.deleted per il ciclo di vita dei link
   • post.published e campaign.created per gli eventi del funnel
5. Clicca su Aggiungi endpoint.

Dopo la creazione, Styrar mostra il tuo secret di firma (whsec_live_… o whsec_test_…). Copialo immediatamente e conservalo nel tuo gestore di secret. Viene mostrato solo una volta. Se lo perdi, usa Ruota secret sull'endpoint e aggiorna il tuo server.

4. Crea un endpoint via API

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"
}

Conserva immediatamente secret. Non viene restituito nelle richieste GET successive. Un array eventTypes vuoto sottoscrive tutti i tipi di evento; la dashboard richiede almeno un evento esplicito.

5. Invia un evento di test

Verifica che il tuo server sia raggiungibile prima di affidarti al traffico live.

Dashboard: Sulla riga dell'endpoint, clicca Invia test. Styrar consegna un evento webhook.test. Dovresti vedere un toast di successo con il codice di stato HTTP.

API:

Authorization: Bearer sty_live_your_api_key

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

Quando il test riesce, il tuo server dovrebbe aver ricevuto un evento webhook.test (vedi Ricevere un evento sul tuo server più sotto).

Controlla Consegne recenti nella dashboard (oppure GET /v1/webhooks/deliveries) se il test fallisce. Problemi comuni:

6. Verifica ed elabora le consegne

Su ogni POST al tuo URL:

1. Analizza Styrar-Signature per estrarre il timestamp t e il digest v1.
2. Rifiuta se t è più vecchio della tua tolleranza (5 minuti consigliati).
3. Calcola l'HMAC-SHA256 di "{t}.{raw_body}" con il secret del tuo endpoint.
4. Confronta con v1 usando un controllo a tempo costante.
5. Esegui il parsing del JSON solo dopo che la verifica ha successo.
6. Deduplica in base a Styrar-Event-Id (consegna at-least-once).

Vedi la sezione Verifica delle firme più sotto per un esempio in Node.js.

7. Vai in produzione

• Mantieni l'endpoint Abilitato nella dashboard.
• Sottoscrivi solo gli eventi di cui hai bisogno (riduce rumore e costi).
• Monitora le Consegne recenti per individuare i fallimenti e usa Riprova quando necessario.
• Ruota il secret se potrebbe essere stato compromesso (Ruota secret nella dashboard o POST …/rotate-secret).

Avvio rapido

1. Ottieni l'accesso API con gli scope webhooks:read e webhooks:write (API key o OAuth).
2. Esponi un receiver HTTPS pubblico e crea un endpoint in Impostazioni → Webhook oppure tramite POST /v1/webhooks/endpoints.
3. Copia il secret di firma quando viene mostrato e conservalo in sicurezza.
4. Invia un evento di test e verifica che il tuo server controlli Styrar-Signature e restituisca 2xx.
5. Elabora gli eventi live con deduplicazione su Styrar-Event-Id.

Autenticazione

La gestione dei webhook richiede un token Bearer con gli scope elencati al passaggio 2 sopra. Le API key con gli scope corrispondenti funzionano allo stesso modo degli access token OAuth.

Tipi di evento

Chiama GET /v1/webhooks/event-types per il catalogo live nel tuo ambiente. Sottoscrivi tipi specifici per endpoint, oppure passa un array eventTypes vuoto per ricevere tutti gli eventi.

webhook.test viene inviato solo quando clicchi Invia test; non viene emesso dalla normale attività del workspace.

Struttura dell'evento

Ogni consegna usa la stessa struttura di livello superiore. I campi specifici dell'evento si trovano sotto data.object:

Esempio completo di consegna (struttura + payload 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"
    }
  }
}

Per i workspace personali, workspace.type è personal e workspace.company_id è null. Il payload può includere company_id: null sugli oggetti link.

Riepilogo eventi

link.created

Si attiva quando un nuovo link breve viene salvato nel tuo workspace.

Usi comuni: Sincronizzare nuovi link con un CRM, attivare automazioni di benvenuto o indicizzare i link in uno store di ricerca esterno.

Campi di 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

Si attiva quando un link breve esistente viene modificato (destinazione, titolo, tag, cartella, impostazioni UTM, ecc.).

Usi comuni: Mantenere i sistemi esterni sincronizzati quando un link cambia senza doverlo ricreare.

Campi di data.object: Gli stessi di link.created (vedi sopra).

{
  "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

Si attiva quando un link breve viene eliminato in modo soft (isActive impostato su false). Il link smette di risolversi pubblicamente ma rimane nella cronologia del workspace.

Usi comuni: Rimuovere link dai catalogi esterni o sospendere le automazioni legate a quel codice breve.

Campi di data.object: Stessa struttura di link.created, con is_active sempre 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

Si attiva dopo che il click di un visitatore viene salvato. Consegnato in modo asincrono (non sul percorso di redirect), quindi aspettati un leggero ritardo sotto carico.

Usi comuni: Analisi dei click in tempo reale, instradamento basato sulla geolocalizzazione nel tuo stack, feed di attività CRM o ingestione nel data warehouse.

Privacy: I payload includono dimensioni geografiche e del dispositivo, non indirizzi IP grezzi.

Campi di 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

Si attiva quando un test A/B su un link breve viene contrassegnato come completato e viene selezionata una variante vincente.

Usi comuni: Registrare gli esiti degli esperimenti, aggiornare le dashboard o attivare campagne di follow-up in base al vincitore.

Campi di data.object:

Ogni elemento in 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

Si attiva quando viene creata una nuova campagna nel tuo workspace.

Usi comuni: Creare cartelle di campagna in strumenti esterni, avviare workflow di attribuzione o notificare gli account manager.

Campi di 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

Si attiva quando un post programmato o immediato viene pubblicato con successo su tutti i target della piattaforma configurati.

Usi comuni: Notificare ai sistemi a valle che il contenuto è online, chiudere il ciclo delle automazioni di campagna o sincronizzare lo stato di pubblicazione con un data warehouse.

Nota: Emesso solo quando ogni target ha successo. I fallimenti parziali non emettono questo evento al momento.

Campi di 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

Ping sintetico inviato solo quando clicchi Invia test nella dashboard o chiami POST /v1/webhooks/endpoints/:id/test.

Usi comuni: Validare l'URL del tuo receiver, il TLS, la verifica della firma e la gestione della risposta prima di andare in produzione.

Campi di data.object:

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

Esempi API

Elenca gli endpoint

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"
  }
]

Ricevere un evento sul tuo server

Quando si attiva un evento sottoscritto, Styrar effettua un POST verso l'URL del tuo endpoint. Questo è il payload che il tuo handler riceve:

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
}

Il body della tua risposta può essere vuoto. Restituisci qualsiasi stato 2xx dopo aver verificato la firma e accettato l'evento. Styrar riprova in caso di risposte non-2xx.

Payload del ping di test

Un'azione Invia test consegna webhook.test con un payload più piccolo:

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"
    }
  }
}

Elenca le consegne recenti

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"
  }
]

Gestione degli endpoint

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

Il secret di firma (whsec_live_… / whsec_test_…) viene restituito esattamente una volta alla creazione e su rotate-secret. Puoi registrare fino a 25 endpoint per ambito di workspace.

Consegne

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

Ogni riga di consegna traccia status, attemptCount, nextAttemptAt, lastStatusCode, lastError e deliveredAt. Ispeziona i fallimenti nella dashboard sotto Impostazioni → Webhook oppure riprova tramite l'API.

Formato di consegna

Ogni evento live è una richiesta HTTP POST al tuo URL di callback. Header e body sono mostrati in Ricevere un evento sul tuo server più sopra.

Campi della struttura:

I payload dei click includono dimensioni geografiche e del dispositivo, non indirizzi IP grezzi.

Verifica delle firme

La firma segue uno schema in stile Stripe. Firma "{timestamp}.{raw_body}" con HMAC-SHA256 usando il secret del tuo endpoint.

1. Analizza Styrar-Signature per estrarre t (timestamp unix) e v1 (digest esadecimale).
2. Rifiuta se t è fuori dalla tua tolleranza (consigliamo 5 minuti).
3. Calcola il digest previsto e confrontalo con v1 usando un controllo a tempo costante.

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
  }
}

Verifica sempre rispetto al body grezzo della richiesta prima di fare il parsing del JSON.

Affidabilità

• Le consegne sono at-least-once. Deduplica usando Styrar-Event-Id o l'id della struttura.
• Le consegne fallite vengono ritentate con backoff esponenziale fino al successo o al numero massimo di tentativi.
• Se il tuo server restituisce HTTP 410, Styrar disabilita automaticamente l'endpoint.
• Rispondi con 2xx non appena hai accettato l'evento; elabora il lavoro pesante in modo asincrono.

Limiti

• HTTPS richiesto in produzione per gli URL di callback.
• 25 endpoint per ambito di workspace personale o aziendale.
• I secret di firma vengono mostrati una sola volta alla creazione e alla rotazione; conservali nel tuo gestore di secret.

Correlati

• Pixel di conversione — traccia le conversioni su pagine di destinazione che non controlli
• Link brevi e QR nel centro assistenza
• API key e app collegate