DEV Community: Asllan Maciel

Como validar webhooks do GitHub com HMAC em PHP e Node.js

Asllan Maciel — Mon, 10 Aug 2026 16:56:57 +0000

Receber um webhook é simples: você expõe um endpoint, recebe um POST e interpreta o JSON.

O problema começa quando esse endpoint confia em qualquer payload que chega.

Se uma aplicação executa ações a partir de webhooks — atualiza dados, inicia deploys, envia notificações ou dispara automações — ela precisa confirmar duas coisas antes de processar o evento:

o payload foi assinado com o secret compartilhado com o GitHub;
o conteúdo recebido não foi modificado no caminho.

Neste artigo, vamos implementar essa verificação com HMAC SHA-256 em PHP e Node.js.

Os exemplos completos e testados estão no repositório github-webhook-security-guide.

Como a assinatura funciona

Ao enviar uma entrega, o GitHub calcula um HMAC usando o corpo original da requisição, o secret configurado no webhook e o algoritmo SHA-256.

O resultado é enviado no header:

X-Hub-Signature-256: sha256=<assinatura hexadecimal>

Seu endpoint precisa calcular a assinatura esperada a partir do corpo bruto recebido e compará-la com o valor do header.

Esse detalhe é importante: não valide a assinatura depois de converter o JSON em objeto e serializá-lo novamente. Qualquer mudança nos bytes — espaços, quebras de linha, Unicode ou ordem de serialização — muda o HMAC.

Checklist mínimo

Leia o corpo bruto antes de interpretar o JSON.
Rejeite secret vazio.
Valide o formato de X-Hub-Signature-256.
Calcule o HMAC com SHA-256.
Compare em tempo constante.
Rejeite assinaturas ausentes ou inválidas.
Só então interprete e processe o evento.

Implementação em PHP 8+

Em PHP, podemos usar hash_hmac() para gerar a assinatura e hash_equals() para realizar a comparação segura:

<?php

declare(strict_types=1);

function verifyGitHubWebhook(
    string $payload,
    string $signatureHeader,
    string $secret
): bool {
    if (
        $secret === '' ||
        !preg_match('/^sha256=[a-f0-9]{64}$/', $signatureHeader)
    ) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac(
        'sha256',
        $payload,
        $secret
    );

    return hash_equals($expected, $signatureHeader);
}

O formato é verificado antes do cálculo. Isso elimina headers ausentes ou malformados e garante que a comparação receba valores com a estrutura esperada.

Um endpoint genérico poderia usar a função assim:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';
$secret = getenv('GITHUB_WEBHOOK_SECRET') ?: '';

if (!verifyGitHubWebhook($payload, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true, flags: JSON_THROW_ON_ERROR);

O secret vem do ambiente, nunca do repositório.

Implementação em Node.js 20+

No Node.js, usamos createHmac() e timingSafeEqual() do módulo nativo node:crypto:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyGitHubWebhook(payload, signatureHeader, secret) {
  if (!secret || !/^sha256=[a-f0-9]{64}$/.test(signatureHeader ?? "")) {
    return false;
  }

  const expected = `sha256=${createHmac("sha256", secret)
    .update(payload)
    .digest("hex")}`;

  const receivedBuffer = Buffer.from(signatureHeader, "utf8");
  const expectedBuffer = Buffer.from(expected, "utf8");

  return (
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer)
  );
}

A verificação do tamanho antes de timingSafeEqual() é obrigatória: a função lança uma exceção quando os buffers têm comprimentos diferentes.

Em frameworks como Express, Fastify ou NestJS, preserve o corpo bruto. Se o middleware de JSON consumir ou transformar o body antes da validação, a assinatura calculada não será a mesma.

Por que não usar uma comparação comum?

Pode parecer suficiente escrever expected === signatureHeader. Mas comparações comuns podem encerrar o trabalho assim que encontram o primeiro caractere diferente. Em determinados cenários, a variação no tempo de resposta pode revelar informações sobre a assinatura esperada.

hash_equals() e timingSafeEqual() foram projetadas para reduzir esse risco por meio de comparação em tempo constante.

A assinatura é apenas a primeira camada

Uma assinatura válida prova que o payload foi assinado com o secret compartilhado. Ela não transforma todo evento em uma ação autorizada para o seu negócio.

Idempotência

Armazene o header X-GitHub-Delivery. Se a mesma entrega chegar novamente, responda de maneira idempotente em vez de repetir efeitos colaterais.

Eventos permitidos

Leia X-GitHub-Event e aceite somente os eventos necessários. Um endpoint criado para push não deve processar qualquer tipo de entrega.

Limites e filas

Limite o tamanho do body, responda rapidamente e envie trabalho pesado para uma fila. O endpoint do webhook não deve executar todo o processamento de forma síncrona.

Logs e retenção

Nunca registre o secret. Evite armazenar payloads completos sem necessidade e defina uma política de retenção para dados que possam conter informações sensíveis.

Autorização de negócio

Mesmo depois de validar o GitHub, confirme se aquele repositório, organização, instalação ou evento pode executar a operação solicitada.

Testando a implementação

O GitHub fornece um vetor público de teste:

secret: It's a Secret to Everybody
payload: Hello, World!
assinatura esperada:
sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17

Use esse valor em testes automatizados e acrescente casos para assinatura correta, assinatura ausente, prefixo inválido, tamanho incorreto, payload modificado e secret vazio.

O repositório do guia inclui exemplos independentes de framework e testes executáveis para PHP e Node.js.

Fluxo recomendado em produção

Receber o POST via HTTPS.
Preservar o corpo bruto.
Validar a assinatura.
Verificar duplicidade por X-GitHub-Delivery.
Filtrar o tipo em X-GitHub-Event.
Persistir um envelope mínimo.
Enviar o processamento para uma fila.
Responder rapidamente ao GitHub.

A validação HMAC é pequena em quantidade de código, mas define a fronteira de confiança de todo o sistema.

Se seu produto recebe webhooks, não trate o endpoint como uma simples rota de entrada. Trate-o como uma interface pública exposta a dados não confiáveis.

Como você trata idempotência e reprocessamento de webhooks nos seus projetos?

Voltei ao DEV: o que mudou depois de 25 anos programando

Asllan Maciel — Mon, 10 Aug 2026 16:46:18 +0000

Programo desde o início dos anos 2000. Nesse tempo, linguagens mudaram, frameworks nasceram e desapareceram, a web amadureceu e a inteligência artificial deixou os laboratórios para entrar no trabalho diário.

Eu também mudei.

Quando publiquei meu primeiro texto aqui no DEV, em 2024, meu perfil ainda mostrava apenas uma parte da minha trajetória. Depois disso, continuei construindo sistemas, empresas, produtos digitais, plataformas SaaS e automações. Mas compartilhei muito pouco desse processo.

Estou voltando para mudar isso.

Construir continua sendo meu jeito de aprender

Ao longo de mais de 25 anos, aprendi que tecnologia só ganha valor quando resolve um problema concreto.

Uma API não é interessante apenas por estar bem estruturada. Ela é interessante quando permite que outro produto exista.

Uma automação não importa apenas porque economiza alguns cliques. Ela importa quando devolve tempo, reduz erros e torna uma operação mais previsível.

Um SaaS não se sustenta apenas com uma boa stack. Ele precisa resolver uma dor real, funcionar em produção e encontrar pessoas dispostas a usá-lo.

Essa ligação entre engenharia, produto e negócio é o que mais me interessa hoje.

O que estou construindo

Atualmente, trabalho em produtos e experimentos que combinam desenvolvimento, inteligência artificial, automação e negócios digitais.

Entre eles estão:

GHDevLog — uma central privada para receber, validar e investigar webhooks do GitHub em tempo real, com foco em segurança e rastreabilidade;
BibliaAPI — uma infraestrutura bíblica para aplicações, com API REST, WordPress, aplicativo mobile e recursos SaaS;
ClariDados — analytics simples para acompanhar visitas, origens, páginas e conversões sem a complexidade das plataformas tradicionais;
Cresça na Fé — uma plataforma de conteúdo, estudos e recursos voltados ao crescimento espiritual;
ferramentas para desenvolvedores, plugins WordPress, APIs e novos SaaS ainda em validação.

Também venho estudando e aplicando agentes de IA, MCPs, workflows e automações em situações reais — não apenas como demonstrações, mas como partes de produtos e operações.

Por que voltar a escrever

Durante muito tempo, grande parte do meu trabalho permaneceu nos bastidores. Muitos sistemas pertencem a clientes ou fazem parte de produtos privados. Isso, porém, não impede que as decisões, os padrões e os aprendizados sejam compartilhados.

Quero usar este espaço para documentar:

decisões de arquitetura e seus trade-offs;
construção e validação de produtos SaaS;
APIs, webhooks e integrações seguras;
PHP, Laravel, WordPress e JavaScript em produção;
agentes de IA, MCPs e automações aplicadas;
Docker, CI/CD, observabilidade e operação;
erros, mudanças de direção e aprendizados de produto;
a relação entre código, monetização e crescimento.

A intenção não é publicar teoria distante da prática. Quero escrever sobre problemas que encontrei, soluções que testei e coisas que ainda estou tentando entender.

O que 25 anos de programação me ensinaram

Alguns princípios sobreviveram a todas as mudanças de stack:

O problema vem antes da ferramenta.

Escolher tecnologia sem compreender a necessidade costuma produzir soluções sofisticadas para o problema errado.
Colocar no ar ensina mais do que planejar indefinidamente.

Construir, observar, aprender e melhorar continua sendo um ciclo poderoso.
Código é apenas uma parte do produto.

Segurança, documentação, experiência, operação, aquisição e sustentabilidade também fazem parte da engenharia de algo útil.
Simplicidade exige experiência.

É fácil adicionar camadas. Difícil é remover o que não precisa existir.
Compartilhar organiza o pensamento.

Explicar uma decisão obriga a separar convicção, hábito e evidência.

O que vem a seguir

Nos próximos textos, pretendo abrir os bastidores dos projetos que estou construindo e transformar experiências práticas em conteúdo que outras pessoas possam testar e adaptar.

Alguns temas que já estão na fila:

como validar assinaturas de webhooks do GitHub com HMAC;
decisões de arquitetura para SaaS multi-tenant;
o que aprendi construindo uma API que serve diferentes produtos;
onde agentes de IA realmente ajudam — e onde apenas adicionam complexidade;
automações e ferramentas para o ecossistema WordPress;
como conectar engenharia, produto e crescimento sem perder o foco técnico.

Se você trabalha com algum desses temas, está construindo um produto ou enfrentando um problema parecido, vamos conversar.

Estou de volta ao DEV para compartilhar enquanto construo — não depois que tudo parecer perfeito.

Porque, depois de 25 anos, uma coisa continua igual: construir ainda é meu jeito de aprender.

Você também voltou a escrever depois de algum tempo? O que fez você recomeçar?

O que é PHP e por que aprender?

Asllan Maciel — Wed, 14 Aug 2024 01:28:02 +0000

Se você está começando no mundo do desenvolvimento web, é provável que já tenha ouvido falar de PHP. Mas o que exatamente é PHP e por que ele é tão amplamente utilizado? Neste post, vamos explorar o que torna o PHP uma escolha popular entre desenvolvedores, suas principais aplicações e por que você deve considerar aprender essa linguagem.

O que é PHP?

PHP, que originalmente significava "Personal Home Page" e agora é conhecido como "Hypertext Preprocessor", é uma linguagem de programação de código aberto utilizada principalmente para o desenvolvimento de aplicações web. Ele foi criado por Rasmus Lerdorf em 1994 e, desde então, se tornou uma das linguagens mais populares para o desenvolvimento de sites dinâmicos.

PHP é uma linguagem server-side, o que significa que seu código é executado no servidor antes de ser enviado ao navegador do usuário. Isso permite que os desenvolvedores criem páginas web dinâmicas, onde o conteúdo pode mudar com base em interações do usuário ou outros fatores, como consultas a bancos de dados.

Por que o PHP é tão popular?

PHP conquistou seu espaço no mundo do desenvolvimento web por várias razões:

Facilidade de Aprendizado: Comparado a outras linguagens de programação, PHP é relativamente fácil de aprender, especialmente para quem já tem experiência com HTML. Sua sintaxe é clara e intuitiva, permitindo que novos desenvolvedores comecem a construir projetos rapidamente.

Comunidade e Suporte: PHP tem uma comunidade enorme e ativa, o que significa que há uma abundância de recursos, tutoriais, e fóruns onde você pode encontrar ajuda. Além disso, muitas bibliotecas e frameworks, como Laravel e Symfony, foram desenvolvidos para facilitar ainda mais o trabalho com PHP.

Integração com Bancos de Dados: PHP se integra facilmente com uma variedade de bancos de dados, como MySQL, PostgreSQL, Oracle, e muitos outros. Isso torna simples a criação de sites e aplicações que dependem de grandes volumes de dados.

Custo-Benefício: Sendo uma linguagem de código aberto, PHP não requer nenhum custo de licença. Isso, aliado à grande quantidade de ferramentas e hospedagens compatíveis, faz do PHP uma opção econômica para desenvolvimento de websites.

Flexibilidade: PHP é uma linguagem extremamente flexível. Ele pode ser usado tanto para criar pequenos scripts quanto para desenvolver grandes aplicações corporativas. Além disso, PHP se integra facilmente com outras tecnologias, como JavaScript, tornando-o ideal para desenvolver aplicações web completas.

Principais Aplicações do PHP

PHP é uma linguagem versátil e pode ser usada para uma ampla gama de projetos. Aqui estão algumas das principais aplicações do PHP:

Desenvolvimento de Sites Dinâmicos: A aplicação mais comum do PHP é no desenvolvimento de sites dinâmicos. Usando PHP, você pode criar páginas que exibem conteúdo diferente dependendo da interação do usuário, como blogs, portais de notícias, e-commerce, etc.

Sistemas de Gerenciamento de Conteúdo (CMS): Muitos dos CMS mais populares, como WordPress, Joomla e Drupal, são construídos com PHP. Esses sistemas permitem que os usuários gerenciem o conteúdo de seus sites sem necessidade de conhecimento técnico avançado.

Aplicações Web Complexas: PHP também é amplamente utilizado para criar aplicações web mais complexas, como plataformas de e-learning, redes sociais, e sistemas de gerenciamento de projetos.

APIs e Microserviços: PHP pode ser usado para construir APIs RESTful, que são utilizadas para conectar diferentes partes de uma aplicação ou para integrar diferentes sistemas.

Por que aprender PHP?

Agora que você sabe o que é PHP e onde ele é usado, vamos falar sobre por que você deve aprender essa linguagem.

Alta Demanda no Mercado: PHP é uma das linguagens mais utilizadas no desenvolvimento web, e há uma alta demanda por desenvolvedores que dominem essa tecnologia. Empresas de todos os portes, desde startups até grandes corporações, buscam profissionais que possam desenvolver e manter suas aplicações PHP.

Grande Ecossistema de Ferramentas: Ao aprender PHP, você terá acesso a um grande ecossistema de ferramentas, frameworks e bibliotecas que podem acelerar o desenvolvimento e ajudar você a criar soluções mais sofisticadas.

Oportunidades de Trabalho como Freelancer: Se você deseja trabalhar como freelancer, PHP oferece uma ampla gama de oportunidades. Muitos pequenos negócios e empreendedores procuram desenvolvedores PHP para criar e manter seus sites, o que pode ser uma excelente fonte de renda extra.

Facilidade de Hospedagem: A maioria das hospedagens web oferece suporte nativo ao PHP, o que significa que você pode facilmente colocar seus projetos no ar sem complicações.

Aprendizado Contínuo: PHP tem evoluído continuamente, com novas versões introduzindo melhorias significativas. Aprender PHP significa também estar sempre atualizado com as últimas tendências e práticas do desenvolvimento web.

Conclusão

PHP é uma linguagem poderosa, flexível e amplamente utilizada que pode abrir muitas portas no mundo do desenvolvimento web. Se você está começando agora ou se já tem experiência com outras linguagens, aprender PHP pode ser um passo estratégico para avançar na sua carreira.

Então, o que está esperando? Pegue seu editor de código, instale o PHP e comece a explorar o vasto universo de possibilidades que essa linguagem oferece. Nos próximos posts, vamos mergulhar mais fundo em como configurar seu ambiente PHP e começar a escrever seus primeiros scripts.

Recursos Adicionais

Documentação Oficial do PHP
Comunidade PHP no Reddit

Se você quer acelerar seu aprendizado em PHP ou precisa de um especialista para impulsionar o seu projeto, estou aqui para ajudar. Vamos transformar suas ideias em realidade com soluções robustas e eficientes. Entre em contato comigo através do asllanmaciel.com.br, explore mais conteúdos sobre WordPress no WP24Horas ou conheça os serviços da minha agência em M3 Marketing Digital.

Vamos juntos criar algo extraordinário?