Webhooks

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

GET https://api.dooki.com.br/v2/{alias}/webhooks/events

Evento	Descrição
order.created	Pedido criado
order.paid	Pedido aprovado
order.status.updated	O status de um pedido foi atualizado
order.invoice.created	Nota fiscal de um pedido foi criada
order.invoice.updated	Nota fiscal de um pedido foi atualizada
transaction.payment.refused	O pagamento de uma transação foi negado
cart.reminder	Notificação de carrinho abandonado
customer.created	Cliente criado
customer.address.created	Endereço do cliente criado
product.created	Produto criado
product.updated	Produto atualizado
product.deleted	Produto excluído
product.inventory.updated	Estoque de produto atualizado

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()

Você encontrará a chave secreta do Webhook logo após ele ser criado.

Listar webhooks

GET https://api.dooki.com.br/v2/{alias}/webhooks

Criar um webhook

POST https://api.dooki.com.br/v2/{alias}/webhooks

Request para incluir um novo webhook

{
    "url": "http://suaurl.com/api/webhooks",
    "events": ["order.created", "cart.reminder"],
    "name": "Nome do webhook"
}

Response de webhook

{
    "data": [
        "id": 1,
        "url": "http://suaurl.com/api/webhooks"
    ]
}

Payload enviado pelo webhook

{
    "event": "order.created",
    "resource": {
        // Payload de um pedido 
    }
}

Parâmetro	Tipo	Obrigatório	Descrição
url	string	Sim	URL que o webhook será enviado.
events	arrays	Sim	Quais eventos serão enviados para o endpoint cadastrado.
name	string	Sim	Nome do webhook.

Atualizar um webhook

PUT https://api.dooki.com.br/v2/{alias}/orders/webhooks/{id}

Excluir um webhook

DELETE https://api.dooki.com.br/v2/{alias}/orders/webhooks/{id}