---
title: "PIX - Cadastro de Webhook"
url: "https://devcenter.stone.com.br/conciliacao-cadastro-de-webhook"
image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_PIX+-+Cadastro+de+Webhook,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9jb25jaWxpYWNhby1jYWRhc3Ryby1kZS13ZWJob29rIg,s_gvij3xMPsXV0oOTP.png"
---

# PIX - Cadastro de Webhook

## [Endpoint](#endpoint)

```text
POST https://conciliation.stone.com.br/v2/webhook
```

### [Headers](#headers)

| Nome         | Obrigatório | Tipo   | Descrição                                                                        |
| :----------- | :---------- | :----- | :------------------------------------------------------------------------------- |
| x-user-type  | não         | string | Deve ser usado somente se você for cliente Stone, utilizando sua chave própria criada diretamente no portal (padrão: client) |
| Content-Type | sim         | string | (padrão: application/json)                                                       |
| accept       | não         | string |                                                                                  |

### [Corpo da requisição](#corpo-da-requisição)

| Campo   | Tipo   | Obrigatório | Descrição |
| :------ | :----- | :---------- | :-------- |
| url     | string | sim         |           |
| headers | string | não         |           |

É necessário cadastrar um **webhook** a partir do qual receberá o tipo do evento e a url de download do arquivo (.csv).

O webhook estará diretamente associado ao ClientId, não sendo possível ter múltiplos webhooks para um mesmo Client. Atualizações no webhook devem ser feitas por meio da rota desta [seção](https://devcenter.stone.com.br/conciliacao-atualizacao-de-webhook).

Apenas eventos de tipo **PIX** utilizam essa estratégia de notificação.

O resultado será informado através do código de status HTTP da resposta.

| HTTP Status Code | Descrição                                                                  |
| :--------------- | :------------------------------------------------------------------------- |
| 201              | Webhook cadastrado com sucesso                                             |
| 400              | Erro nos parâmetros informados                                             |
| 404              | Erro no formato da URL ou no método enviado                                |
| 409              | Erro de conflito, pois webhook já foi cadastrado                           |
| 500              | Ocorreu um erro interno na API, por favor nos informe                      |
| 503              | Um dos sistemas da Stone falhou, por favor nos informe                     |
| 504              | Ocorreu um timeout e não foi possível concluir o trabalho, tente novamente |

**Validação da URL de notificação**

Ao cadastrar um webhook, nós enviaremos uma requisição de validação (HTTP POST) para a URL informada antes de concluir a operação. A URL precisa responder com sucesso (HTTP 2xx) dentro de 3 segundos; caso contrário, a requisição será rejeitada e o webhook não é cadastrado.

Corpo da notificação enviada

```json
{
    "type": "validation_notification"
}
```

Authorization: Conciliadoras

[Como gerar seu token de acesso](https://devcenter.stone.com.br/conciliacao-gerando-seu-token-de-acesso)

Para autenticação nesse endpoint, é necessário utilizar um token de acesso válido atrelado a qualquer cliente da conciliadora. Como o cadastro de webhook é feito pelo ClientId da conciliadora, só precisa ser feito uma vez e o mesmo será usado para todos os clientes.

Authorization: Cliente Stone

Para se autenticar conosco você deve enviar a Chave de API no cabeçalho Authorization, seguindo o padrão da [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).

Para montar a requisição Basic Auth, você deve utilizar sua Chave Secreta da seguinte maneira: **User**: _chave_ **Password**: _vazio_

---

**Jornada: [Baixar o arquivo de conciliação](https://devcenter.stone.com.br/conciliacao-extrato-da-agenda-stone)**  
Etapa 7 de 10

[**Etapa anterior**Notificação via Webhook](https://devcenter.stone.com.br/conciliacao-notificacao-via-webhook)[**Próxima etapa**PIX - Atualização de Webhook](https://devcenter.stone.com.br/conciliacao-atualizacao-de-webhook)

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.