Integração entre sistemas é onde a maioria dos incidentes acontece. O sistema do outro cai, demora, devolve erro 500, repete a entrega. Se a sua integração não está preparada, ela vira fonte de chamado. Este texto cobre o que fazemos para integrações aguentarem o mundo real.

Filas e retries

Toda chamada externa sai do request síncrono e vai para uma fila. Laravel já traz o necessário:

  • Job com tries, backoff e retryUntil.
  • Fila separada para integrações (não bloqueia e-mails, por exemplo).
  • failed_jobs monitorado.
class SyncOrderToErp implements ShouldQueue
{
    public $tries = 5;
    public $backoff = [10, 30, 60, 120];
}

Idempotência

Se o mesmo evento chega duas vezes (e vai chegar), o resultado deve ser o mesmo. Chave de idempotência na camada de entrada:

  • Header Idempotency-Key em POSTs sensíveis.
  • Tabela idempotency_keys guardando resposta por chave.
  • Reentrega devolve a resposta original, sem reprocessar.

Webhooks

Webhook é contrato: o outro lado espera resposta rápida e confiável.

  1. Recebe, valida assinatura, responde 200 imediatamente.
  2. Persiste o payload.
  3. Processa em fila.
  4. Em caso de falha, fila + retry cuidam — não o endpoint.

Observabilidade

Sem logs estruturados, integração é caixa-preta. Cada job registra: quem chamou, qual endpoint, status, duração, payload (sem PII). Métricas de taxa de erro e latência viram alertas.

Integração robusta é menos sobre o protocolo e mais sobre assumir que tudo vai falhar eventualmente — e estar pronto para isso.