Base URL

https://lip-backend-1064145932505.southamerica-east1.run.app

Endpoints

• POST /api/external/webhooks
• GET /api/external/webhooks
• GET /api/external/webhooks/{id}
• PATCH /api/external/webhooks/{id}
• DELETE /api/external/webhooks/{id}

Escopo necessario: webhooks:manage

Criar webhook

Body:

• name (string, obrigatorio)
• url (string, obrigatorio)
• events (array de strings, obrigatorio)
• secret (string, opcional; se omitido, geramos automaticamente)
• headers (objeto, opcional)
• retryConfig (objeto, opcional)

retryConfig:

• maxRetries (number, default 3)
• backoffMs (number, default 1000)

Exemplo:

Copiar

Atualizar webhook

PATCH /api/external/webhooks/{id}

Campos comuns:

• name, url, events, secret, headers, retryConfig, isActive

Eventos suportados

• WHATSAPP_RECEIVED
• WHATSAPP_SENT
• WHATSAPP_DELIVERED
• WHATSAPP_READ
• WHATSAPP_FAILED
• EMAIL_SENT
• EMAIL_DELIVERED
• EMAIL_OPENED
• EMAIL_CLICKED
• EMAIL_BOUNCED
• EMAIL_UNSUBSCRIBED
• EMAIL_COMPLAINED
• CAMPAIGN_SCHEDULED
• CAMPAIGN_STARTED
• CAMPAIGN_COMPLETED
• CAMPAIGN_FAILED
• CAMPAIGN_PAUSED
• CAMPAIGN_CANCELLED
• CONTACT_SUBSCRIBED
• CONTACT_UNSUBSCRIBED
• CONTACT_CONSENT_GIVEN
• CONTACT_CONSENT_REVOKED

Payload

Estrutura base:

Copiar

Exemplo: WHATSAPP_RECEIVED

Copiar

Exemplo: WHATSAPP_SENT

Copiar

Exemplo: EMAIL_SENT

Copiar

Headers enviados

Cada entrega inclui:

• Content-Type: application/json
• User-Agent: LIP-Webhook/1.0
• X-LIP-Event: <EVENTO>
• X-LIP-Timestamp: <timestamp>
• X-LIP-Attempt: <tentativa>
• X-LIP-Signature: <assinatura> (quando secret estiver configurado)

Assinatura HMAC

A assinatura e um HMAC SHA-256 do payload com o timestamp:

signature = HMAC_SHA256(secret, "{timestamp}.{payload_json}")

Recomendacao:

• Use o corpo bruto da requisicao para validar o HMAC.

Exemplo de validacao (pseudo):

Copiar

Retries e timeouts

• Timeout de entrega: 30s
• Retries: exponencial com backoffMs e maxRetries
• Retornando 2xx o webhook e considerado entregue