---
title: "Webhooks"
url: "https://devcenter.stone.com.br/foundations-webhooks"
image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_Webhooks,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9mb3VuZGF0aW9ucy13ZWJob29rcyI,s_qgp6EhoFCua6q3Bi.png"
---

## **Webhooks**

Notificações HTTP em tempo real, com assinatura HMAC e retry.

Webhooks são notificações HTTP POST enviadas pela Stone sempre que um evento relevante acontece — pagamento aprovado, conta criada, transferência liquidada, transação na maquininha conciliada.

## [Eventos disponíveis (parcial)](#eventos-disponíveis-parcial)

```text
charge.created            charge.paid              charge.failed
charge.refunded           charge.disputed
checkout.completed        checkout.expired
pos.transaction.created   pos.transaction.settled  pos.terminal.online
banking.account.opened    banking.transfer.completed
pix.received              pix.return.completed
```

## [Assinatura — HMAC-SHA256](#assinatura-hmac-sha256)

Todo webhook traz o header `X-Stone-Signature` com a assinatura do corpo:

```text
X-Stone-Signature: t=1714248000,v1=5257a869e7ec...
```

Node.js

```javascript
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const [t, v1] = signatureHeader.split(',').map(p => p.split('=')[1]);
  const signed = \`\${t}.\${rawBody}\`;
  const expected = crypto.createHmac('sha256', secret).update(signed).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
```

Python

```python
import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    parts = dict(p.split('=') for p in signature.split(','))
    signed = f"{parts['t']}.{raw_body.decode()}".encode()
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts['v1'])
```

## [Retry e idempotência de entrega](#retry-e-idempotência-de-entrega)

-   Tentamos entregar por até **72 horas**, com backoff exponencial (1m, 5m, 30m, 2h, 6h…)
-   Cada entrega traz `X-Stone-Delivery-Id` único — use para deduplicar
-   Responda **2xx em até 10s**. Qualquer outra coisa = retry.

Boa prática

Trate o webhook como _fato bruto_. Persista o evento, responda 200, e processe assincronamente. Reduz drasticamente os retries e melhora a observabilidade.

## [Veja também](#veja-também)

[**Autenticação**OAuth2, API Key e mTLS — três modos, mesmas credenciais.](https://devcenter.stone.com.br/foundations-auth)[**Ambientes**Sandbox vs produção, dados de teste, migração.](https://devcenter.stone.com.br/foundations-environments)[**Tratamento de erros**RFC 7807 Problem Details — formato único.](https://devcenter.stone.com.br/foundations-errors)[**Idempotência**Idempotency-Key em todas as escritas — sem duplicatas em retries.](https://devcenter.stone.com.br/foundations-idempotency)

Siga a Stone nas redes sociais

[](https://www.facebook.com/stonepagamentos/)[](https://x.com/sejastone/)[](https://www.instagram.com/stone/)[](https://br.linkedin.com/company/stone-co)[](https://www.youtube.com/channel/UCk4L4JykgoDkN8YeuxkNqIQ)

© Stone Instituição de Pagamento S.A. CNPJ 16.501.555/0001-57

Av. Rebouças, 2880, 4º andar, Pinheiros, CEP 05.402-500 – São Paulo/SP

Instituição de pagamento autorizada pelo Banco Central do Brasil, nas modalidades de credenciadora e emissora de moeda eletrônica.