Integrações de API seguras: Stripe, Shopify, Salesforce, webhooks

O que é

Uma integração segura protege três coisas: as credenciais que concedem acesso, os dados que circulam entre os sistemas e a integridade dos eventos de negócio que disparam ações. As credenciais incluem chaves de API, tokens OAuth e client secrets; elas devem ficar apenas no servidor, em um gerenciador de segredos ou em uma configuração de ambiente protegida, com as permissões mais restritas de que a integração precisa. Os dados em trânsito usam HTTPS, e os dados em repouso se limitam ao que o negócio realmente precisa armazenar. A integridade dos eventos depende de verificar se os webhooks recebidos realmente vêm do provedor. A Stripe, por exemplo, assina os eventos de webhook com um segredo de assinatura e fornece um cabeçalho de assinatura que seu endpoint deve verificar; a Shopify assina os webhooks com um cabeçalho HMAC; as integrações com o Salesforce normalmente usam OAuth por meio de um connected app ou de seu equivalente mais recente, um external client app, com permissões delimitadas. A confiabilidade também importa. Webhooks podem chegar atrasados, mais de uma vez ou fora de ordem, por isso os handlers devem ser idempotentes, e as chamadas de saída devem lidar com limites de taxa e novas tentativas sem duplicar cobranças, pedidos ou registros. É por isso que a Stripe oferece suporte a chaves de idempotência.

A quem se destina

Este guia é destinado a:

• Equipes que conectam pagamentos, assinaturas ou fluxos de checkout aos próprios sistemas
• Empresas de e-commerce que sincronizam pedidos, estoque ou clientes entre a Shopify e outras plataformas
• Empresas que integram dados de CRM do Salesforce a ferramentas internas ou portais de clientes
• Responsáveis por produtos que revisam trabalhos de integração entregues por uma agência ou por um freelancer

O que ajuda a esclarecer

Trabalhar os controles ajuda a esclarecer:

• Onde as credenciais são armazenadas, quem pode acessá-las e como são rotacionadas
• Se os endpoints de webhook verificam as assinaturas e rejeitam requisições não assinadas ou reenviadas
• Como falhas, novas tentativas e duplicidades são tratadas sem corromper dados
• Quais dados são copiados entre os sistemas e se todos eles precisam ser

O que está incluído

• Mantenha as chaves de API secretas apenas no servidor; use chaves publicáveis ou públicas nos clientes quando o provedor oferecer suporte
• Armazene segredos em um gerenciador de segredos ou em configuração protegida, nunca em repositórios de código-fonte
• Solicite os escopos e permissões mais restritos; use credenciais separadas para cada ambiente
• Rotacione as credenciais periodicamente e imediatamente após mudanças de pessoal ou de fornecedores
• Verifique as assinaturas dos webhooks pelo método documentado pelo provedor e rejeite as requisições que falharem
• Verifique os registros de data e hora dos eventos para reduzir o risco de reenvio (replay) e registre os IDs dos eventos processados
• Torne os handlers idempotentes para que eventos repetidos não criem ações duplicadas
• Use chaves de idempotência ou salvaguardas equivalentes nas operações de criação de saída, quando houver suporte
• Trate os limites de taxa com backoff e coloque o trabalho em fila em vez de descartá-lo
• Registre em log os eventos de integração sem registrar segredos, dados de cartão ou dados pessoais desnecessários
• Alerte alguém quando jobs de sincronização ou webhooks falharem repetidamente
• Teste nos modos sandbox ou de teste do provedor antes de passar para credenciais de produção

O que não está incluído

• Validação de conformidade com o PCI DSS ou aprovação de processadores de pagamento
• Operações antifraude ou gestão de chargebacks
• Afirmação de que seguir esses controles evita qualquer incidente de integração
• Operação de plataformas de terceiros, que continua sendo responsabilidade dos provedores

Quando escolher esta opção

Use esta checklist ao projetar uma nova integração, antes de entrar em produção, ao herdar código de integração de outra equipe e após qualquer incidente envolvendo pagamentos duplicados, pedidos ausentes ou acesso inesperado a dados. Ela é especialmente importante quando uma integração pode disparar ações financeiras, como cobranças, reembolsos ou alterações de assinatura, ou pode expor registros de clientes.

A Nossa Abordagem

Trate cada integração como um pequeno produto, com responsável, documentação e monitoramento próprios. Comece por um inventário de integrações, credenciais e endpoints de webhook; muitas organizações descobrem chaves que ninguém se lembra de ter criado. Em seguida, aplique os controles acima por ordem de risco: primeiro segredos e verificação de assinaturas, depois idempotência e tratamento de falhas e, por fim, logs e alertas. Nosso serviço Secure Backend & API Engineering projeta e entrega trabalhos de backend e de integração com um contrato de API, um resumo de testes e um runbook de operações, sendo o acesso à produção e os dados de clientes utilizados apenas mediante autorização expressa por escrito. Quando há lógica de pagamento e assinaturas envolvida, o serviço Subscription & Payment Infrastructure Security pode revisar separadamente os fluxos de pagamento e de direitos de acesso acordados. Se você quiser uma verificação independente dos endpoints de integração existentes, uma revisão de segurança de aplicações pode incluí-los no escopo.

Secure Backend & API Engineering

Perguntas frequentes

Artigos relacionados