Através do recurso de webhooks, a plataforma enviará um POST para as URLS cadastradas sempre quando algum evento acontecer. O payload do recurso é enviado com todas as includes disponíveis.

Eventos disponíveis

EventoDescrição
order.createdPedido criado
order.paidPedido aprovado
order.status.updatedO status de um pedido foi atualizado
order.invoice.createdNota fiscal de um pedido foi criada
order.invoice.updatedNota fiscal de um pedido foi atualizada
transaction.payment.refusedO pagamento de uma transação foi negado
cart.reminderNotificação de carrinho abandonado
customer.createdCliente criado
customer.address.createdEndereço do cliente criado
product.createdProduto criado
product.updatedProduto atualizado
product.deletedProduto excluído
product.inventory.updatedEstoque de produto atualizado
cashback.expiringUm Cashback está expirando

Segurança

A validação do webhook serve para verificar se realmente ele foi enviado pela Yampi, e é de extrema importância a sua utilização para que suas transações estejam seguras.

Para fazer a validação, são necessárias duas informações de nosso webhook:

  • Valor do header X-Yampi-Hmac-SHA256. Vamos chamar esse valor de “assinatura do webhook”;
  • Corpo da requisição (no mesmo formato mostrado na seção anterior). Com esses dois valores, basta realizar o base64 do algoritmo HMAC-SHA256 do corpo da requisição utilizando a chave secreta do Webhook e comparar com a assinatura do webhook. Se os valores forem iguais, excelente. Caso contrário, não fomos nós que enviamos essa requisição!

Veja abaixo um exemplo de função em PHP que calcula a assinatura:

function hmac_signature(array $body, $webHookSecret)
{
    $payload = json_encode($body);

    return base64_encode(hash_hmac('sha256', $payload, $webHookSecret, true));
}

// Calculando a assinatura

$body = [
    'event' => 'order.created',
    'time' => '2020-06-20 00:00:00',
    'resource' => [
        'id' => 1121333,
        // Aqui vem todo o payload do resource.
    ],
];

$signature = hmac_signature($body, 'wh_FBmkbmkMSAKmkMBKmdsbUUHjnlmlm');

echo $signature; // Output: NzhjMmM3NzcwZDM5NmM1ZWYxNjhjMDI5NmVhYjgzOTFlNDNlNmU0OWU5ZWZhMTRiYTIyNTI0NzdhNTVhZTMxNQ

Importante: é esperado que o base64 seja calculado em cima do hmac em formato binário. No exemplo em PHP, é o terceiro argumento da função hash_hmac()

APIs

Você pode criar e gerenciar webhooks através da API de Webhooks. Para mais informações, consulte a documentação da API de Webhooks.