Webhooks

Os webhooks do Styrar enviam notificações HTTP assinadas quando os recursos do seu espaço de trabalho são alterados. Use-os para sincronizar links e cliques com um CRM, acionar automações na sua stack ou transmitir eventos de funil para um data warehouse.

Isto substitui a antiga API de webhooks apenas para links (/v1/link-webhooks), agora descontinuada. As novas integrações devem usar apenas /v1/webhooks/*.

Configurar um webhook

Siga estes passos para sair do zero e chegar a um endpoint verificado e pronto para produção.

1. Prepare o seu URL recetor

O seu servidor precisa de um URL HTTPS público que aceite requisições POST com um corpo JSON. Em produção, os URLs de callback devem usar HTTPS.

O seu handler deve:

• Ler o corpo da requisição em bruto como string ou buffer (não analisar o JSON antes de verificar a assinatura).
• Ler os cabeçalhos Styrar-Signature, Styrar-Event-Id e Styrar-Event-Type.
• Verificar a assinatura (ver a secção Verificar assinaturas abaixo).
• Devolver 2xx rapidamente após o evento ser aceite. Coloque o trabalho pesado numa fila assíncrona.

Exemplo de caminho: https://your-app.com/webhooks/styrar

O Styrar não consegue entregar a endereços privados ou loopback como localhost.

2. Obtenha acesso à API (para configuração programática)

Se criar endpoints através da API em vez do painel, precisa de um token Bearer com:

Crie uma chave de API em Definições → Chaves de API com webhooks:read e webhooks:write, ou use um token de acesso OAuth de uma app ligada com os mesmos âmbitos.

Para espaços de trabalho de empresa, passe companyId nas requisições de listagem e criação.

3. Crie um endpoint no painel

1. Inicie sessão e abra Definições → Webhooks (/settings/webhooks).
2. Em Endpoints, introduza o seu URL do endpoint (o callback HTTPS público).
3. Opcionalmente, adicione uma Descrição (por exemplo, "Sincronização de CRM em produção").
4. Selecione os Eventos que deseja (é necessário pelo menos um). Escolhas comuns:
   • link.clicked para rastreio de cliques
   • link.created / link.updated / link.deleted para o ciclo de vida dos links
   • post.published e campaign.created para eventos de funil
5. Clique em Adicionar endpoint.

Depois da criação, o Styrar mostra o seu segredo de assinatura (whsec_live_… ou whsec_test_…). Copie-o imediatamente e guarde-o no seu gestor de segredos. É mostrado apenas uma vez. Se o perder, use Rotar segredo no endpoint e atualize o seu servidor.

4. Crie um endpoint através da 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"
}

Guarde o secret imediatamente. Não é devolvido em requisições GET posteriores. Um array eventTypes vazio subscreve todos os tipos de evento; o painel exige pelo menos um evento explícito.

5. Envie um evento de teste

Confirme que o seu servidor é alcançável antes de confiar no tráfego real.

Painel: Na linha do endpoint, clique em Enviar teste. O Styrar entrega um evento webhook.test. Deverá ver uma notificação de sucesso com o código de estado HTTP.

API:

Authorization: Bearer sty_live_your_api_key

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

Quando o teste tiver sucesso, o seu servidor deverá ter recebido um evento webhook.test (ver Receber um evento no seu servidor abaixo).

Verifique Entregas recentes no painel (ou GET /v1/webhooks/deliveries) se o teste falhar. Problemas comuns:

6. Verifique e processe as entregas

Em cada POST para o seu URL:

1. Analise o Styrar-Signature para obter o timestamp t e o resumo v1.
2. Rejeite se t for mais antigo do que a sua tolerância (recomenda-se 5 minutos).
3. Calcule o HMAC-SHA256 de "{t}.{raw_body}" com o segredo do seu endpoint.
4. Compare com v1 usando uma verificação em tempo constante.
5. Analise o JSON apenas após a verificação ter sucesso.
6. Elimine duplicados com base no Styrar-Event-Id (entrega pelo menos uma vez).

Ver a secção Verificar assinaturas abaixo para um exemplo em Node.js.

7. Entre em produção

• Mantenha o endpoint Ativado no painel.
• Subscreva apenas os eventos de que necessita (reduz ruído e custo).
• Monitorize Entregas recentes para falhas e use Repetir quando necessário.
• Rote o segredo se este puder ter sido exposto (Rotar segredo no painel ou POST …/rotate-secret).

Início rápido

1. Obtenha acesso à API com os âmbitos webhooks:read e webhooks:write (chave de API ou OAuth).
2. Exponha um recetor HTTPS público e crie um endpoint em Definições → Webhooks ou via POST /v1/webhooks/endpoints.
3. Copie o segredo de assinatura quando for mostrado e guarde-o em segurança.
4. Envie um evento de teste e confirme que o seu servidor verifica o Styrar-Signature e devolve 2xx.
5. Processe eventos reais com eliminação de duplicados com base no Styrar-Event-Id.

Autenticação

A gestão de webhooks requer um token Bearer com os âmbitos indicados no passo 2 acima. As chaves de API com os âmbitos correspondentes funcionam da mesma forma que os tokens de acesso OAuth.

Tipos de evento

Chame GET /v1/webhooks/event-types para obter o catálogo em tempo real no seu ambiente. Subscreva tipos específicos por endpoint, ou passe um array eventTypes vazio para receber todos os eventos.

O webhook.test só é enviado quando clica em Enviar teste; não é emitido pela atividade normal do espaço de trabalho.

Envelope do evento

Cada entrega usa a mesma estrutura de topo. Os campos específicos do evento estão em data.object:

Exemplo completo de entrega (envelope + payload de 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"
    }
  }
}

Em espaços de trabalho pessoais, workspace.type é personal e workspace.company_id é null. O payload pode incluir company_id: null nos objetos de link.

Resumo dos eventos

link.created

Ocorre quando um novo link curto é guardado no seu espaço de trabalho.

Usos comuns: Sincronizar novos links com um CRM, acionar automações de boas-vindas, ou indexar links numa pesquisa externa.

Campos de 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

Ocorre quando um link curto existente é modificado (destino, título, etiquetas, pasta, definições UTM, etc.).

Usos comuns: Manter sistemas externos sincronizados quando um link muda sem o recriar.

Campos de data.object: Iguais aos de link.created (ver acima).

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

Ocorre quando um link curto é eliminado de forma reversível (isActive definido como false). O link deixa de resolver publicamente, mas permanece no histórico do seu espaço de trabalho.

Usos comuns: Remover links de catálogos externos ou pausar automações associadas a esse código curto.

Campos de data.object: Mesma estrutura de link.created, com 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

Ocorre depois de um clique de visitante ser persistido. Entregue de forma assíncrona (não no caminho do redirecionamento), por isso é normal um ligeiro atraso sob carga.

Usos comuns: Análises de cliques em tempo real, encaminhamento por geolocalização na sua stack, feeds de atividade de CRM, ou ingestão num warehouse.

Privacidade: Os payloads incluem dimensões de geolocalização e dispositivo, não endereços IP em bruto.

Campos de 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

Ocorre quando um teste A/B num link curto é marcado como concluído e uma variante vencedora é selecionada.

Usos comuns: Registar resultados de experiências, atualizar painéis, ou acionar campanhas de seguimento com base na vencedora.

Campos de data.object:

Cada item em 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

Ocorre quando uma nova campanha é criada no seu espaço de trabalho.

Usos comuns: Provisionar pastas de campanha em ferramentas externas, iniciar fluxos de atribuição, ou notificar gestores de conta.

Campos de 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

Ocorre quando uma publicação agendada ou imediata é publicada com sucesso em todos os destinos de plataforma configurados.

Usos comuns: Notificar sistemas a jusante de que o conteúdo está ativo, fechar o ciclo em automações de campanha, ou sincronizar o estado de publicação com um data warehouse.

Nota: Apenas emitido quando todos os destinos têm sucesso. Falhas parciais não emitem este evento atualmente.

Campos de 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 sintético enviado apenas quando clica em Enviar teste no painel ou chama POST /v1/webhooks/endpoints/:id/test.

Usos comuns: Validar o seu URL recetor, TLS, verificação de assinatura e tratamento de respostas antes de entrar em produção.

Campos de data.object:

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

Exemplos de API

Listar endpoints

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

Receber um evento no seu servidor

Quando um evento subscrito ocorre, o Styrar faz POST para o URL do seu endpoint. Este é o payload que o seu handler recebe:

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
}

O corpo da sua resposta pode estar vazio. Devolva qualquer estado 2xx após verificar a assinatura e aceitar o evento. O Styrar repete em respostas que não sejam 2xx.

Payload do ping de teste

Uma ação Enviar teste entrega webhook.test com um payload mais pequeno:

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

Listar entregas recentes

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

Gerir endpoints

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

O segredo de assinatura (whsec_live_… / whsec_test_…) é devolvido exatamente uma vez na criação e em rotate-secret. Pode registar até 25 endpoints por âmbito de espaço de trabalho.

Entregas

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

Cada linha de entrega regista status, attemptCount, nextAttemptAt, lastStatusCode, lastError e deliveredAt. Inspecione falhas no painel em Definições → Webhooks ou repita através da API.

Formato de entrega

Cada evento real é um POST HTTP para o seu URL de callback. Os cabeçalhos e o corpo são mostrados em Receber um evento no seu servidor acima.

Campos do envelope:

Os payloads de clique incluem dimensões de geolocalização e dispositivo, não endereços IP em bruto.

Verificar assinaturas

A assinatura segue um esquema ao estilo Stripe. Assina "{timestamp}.{raw_body}" com HMAC-SHA256 usando o segredo do seu endpoint.

1. Analise o Styrar-Signature para obter t (timestamp Unix) e v1 (resumo hexadecimal).
2. Rejeite se t estiver fora da sua tolerância (recomendamos 5 minutos).
3. Calcule o resumo esperado e compare com v1 usando uma verificação em tempo constante.

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

Verifique sempre contra o corpo da requisição em bruto antes de analisar o JSON.

Fiabilidade

• As entregas são pelo menos uma vez. Elimine duplicados usando Styrar-Event-Id ou o id do envelope.
• As entregas falhadas repetem com recuo exponencial até terem sucesso ou atingirem o número máximo de tentativas.
• Se o seu servidor devolver HTTP 410, o Styrar desativa o endpoint automaticamente.
• Responda com 2xx logo que tiver aceitado o evento; processe o trabalho pesado de forma assíncrona.

Limites

• HTTPS obrigatório em produção para os URLs de callback.
• 25 endpoints por âmbito de espaço de trabalho pessoal ou de empresa.
• Os segredos de assinatura são mostrados uma vez na criação e na rotação; guarde-os no seu gestor de segredos.

Relacionado

• Pixel de conversão — rastreie conversões em páginas de destino que não controla
• Links curtos e QR no centro de ajuda
• Chaves de API e apps ligadas