# Webhooks

Webhooks (ou callbacks) são retornos de chamada de HTTP definidos pelo usuário, que são acionados por eventos específicos. Sempre que ocorrer um evento de acionamento, a API da Sinch coletará os dados e imediatamente enviará uma notificação (solicitação HTTP) a URL escolhida pelo cliente atualizando o status das mensagens enviadas ou indicando quando você receber uma mensagem.

Quando o cliente enviar uma mensagem a você, API da Sinch Messaging enviará uma notificação de solicitação HTTP POST à URL do **Webhook** com os detalhes.

{% hint style="warning" %}
**`É importante que seu Webhook retorne uma resposta HTTPS 200 OK às notificações (em até 200 ms ou de maneira assíncrona). Caso contrário, a API da Sinch Messaging considerará essa notificação com falha e tentará novamente após um atraso.`**
{% endhint %}

{% hint style="danger" %}
**Importante: A URL onde você irá receber os Webhooks precisa ser configurado por nosso time de suporte.**
{% endhint %}

O formato do retorno seguirá a seguinte descrição:

<table><thead><tr><th width="178">Campo</th><th width="419">Detalhes</th><th>Tipo</th></tr></thead><tbody><tr><td>total</td><td>Número de callbacks retornados.</td><td>String</td></tr><tr><td>data</td><td>Dados retornados no Callback.</td><td>Data[]</td></tr><tr><td>clientInfo</td><td>Informações do cliente.</td><td>ClientInfo</td></tr><tr><td>conversationID</td><td></td><td>String</td></tr></tbody></table>

### Data: <a href="#data" id="data"></a>

<table><thead><tr><th width="187">Campo</th><th width="430">Detalhes</th><th>Tipo</th></tr></thead><tbody><tr><td>id</td><td>id da mensagem.</td><td>String</td></tr><tr><td>correlationId</td><td>Caso tenha sido especificado um correlationId no envio da mensagem, ele irá aparecer aqui.</td><td>String</td></tr><tr><td>destination</td><td>Número do telefone que a mensagem foi enviada (incluindo código de pais). Exemplo: 5511900000000.</td><td>String</td></tr><tr><td>origin</td><td>Número da Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000.</td><td>String</td></tr><tr><td>campaignId</td><td>Caso tenha sido especificado um campaignID no envio da mensagem, ele irá aparecer aqui.</td><td>String</td></tr><tr><td>campaignAlias</td><td>Caso tenha sido especificado um campaignAlias no envio da mensagem, ele irá aparecer aqui.</td><td>String</td></tr><tr><td>extraInfo</td><td>Informação extra enviada com a mensagem original.</td><td>String</td></tr><tr><td>sent</td><td>Indica se a mensagem foi enviada.</td><td>Boolean</td></tr><tr><td>sentStatusCode</td><td>Código de Status gerado pela Sinch Messaging WhatsApp API para a mensagem indicando o status de envio.</td><td>Number</td></tr><tr><td>sentStatus</td><td>Descrição do status de envio.</td><td>Boolean</td></tr><tr><td>sentDate</td><td>Data em que a mensagem foi enviada. Formato: yyyy-MM-dd’T'HH:mm:ssZ.</td><td>String</td></tr><tr><td>sentAt</td><td>Horário em que a mensagem foi enviada, usando Unix_time format</td><td>Number</td></tr><tr><td>delivered</td><td>Indica se a mensagem foi entregue no destino.</td><td>Boolean</td></tr><tr><td>deliveredStatusCode</td><td>Código de Status gerado pela Sinch Messaging WhatsApp API indicando se a mensagem foi entregue.</td><td>Number</td></tr><tr><td>deliveredStatus</td><td>Descrição do status de entrega.</td><td>String</td></tr><tr><td>deliveredDate</td><td>Data em que a mensagem foi entregue. Formato:: yyyy-MM-dd’T'HH:mm:ssZ</td><td>String</td></tr><tr><td>deliveredAt</td><td>Horário em que a mensagem foi entregue, usando Unix_time format</td><td>Number</td></tr><tr><td>read</td><td>Indica se a mensagem foi lida pelo destinatário.</td><td>Boolean</td></tr><tr><td>readDate</td><td>Data em que a mensagem foi lida. Formato: yyyy-MM-dd’T'HH:mm:ssZ</td><td>String</td></tr><tr><td>readAt</td><td>Horário em que a mensagem foi lida, usando Unix_time format</td><td>String</td></tr><tr><td>updatedDate</td><td>Data em que o status da mensagem foi atualizado. Formato: yyyy-MM-dd’T'HH:mm:ssZ</td><td>String</td></tr><tr><td>updatedAt</td><td>Horário em que o status da mensagem foi atualizado, usando Unix_time format</td><td>String</td></tr><tr><td>type</td><td>O tipo de entidade a que se refere este objeto de status. Atualmente, a única opção disponível é “mensagem”.</td><td>String</td></tr></tbody></table>

> Exemplo de requisição com Webhook

{% tabs %}
{% tab title="cURL" %}

```
{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}
```

{% endtab %}

{% tab title="Ruby" %}

```
{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}
```

{% endtab %}

{% tab title="Python" %}

```
{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}
```

{% endtab %}

{% tab title="PHP" %}

```
{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}
```

{% endtab %}

{% tab title="Java" %}

```
{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891,
      "type": "MESSAGE"
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}
```

{% endtab %}
{% endtabs %}

### ClientInfo: <a href="#clientinfo" id="clientinfo"></a>

<table><thead><tr><th width="177">Campo</th><th width="410">Detalhes</th><th>Tipo</th></tr></thead><tbody><tr><td>customerId</td><td>Código de identificação do cliente.</td><td>Number</td></tr><tr><td>subAccountId</td><td>Código de identificação da subconta.</td><td>Number</td></tr><tr><td>userId</td><td>Código de identificação do usuário.</td><td>Number</td></tr></tbody></table>

### Status <a href="#status" id="status"></a>

Descrição dos Status que podem ser enviados no callback:

<table><thead><tr><th width="221">Status</th><th>Descrição</th><th>Equivalente ao WhatsApp para dispositivos móveis</th></tr></thead><tbody><tr><td>SENT_SUCCESS</td><td>Mensagem recebida pelo servidor do WhatsApp</td><td>Uma marca de seleção</td></tr><tr><td>DELIVERED_SUCCESS</td><td>Mensagem entregue para o destinatário</td><td>Duas marcas de seleção</td></tr><tr><td>READ_SUCCESS</td><td>Mensagem lida pelo destinatário</td><td>Duas marcas de seleção azuis</td></tr></tbody></table>

### Outros Status <a href="#outros-status" id="outros-status"></a>

Esses são os códigos retornados nos campos **sentStatusCode e deliveredStatusCode.**

<table><thead><tr><th width="163">Código de envio</th><th width="171">Código de entrega</th><th width="186">Status</th><th>Significado</th></tr></thead><tbody><tr><td>102</td><td></td><td>CARRIER COMMUNICATION ERROR</td><td>Erro ao fazer upload de mídia para o WhatsApp</td></tr><tr><td>103</td><td></td><td>REJECTED_BY_CARRIER</td><td>Ocorreu erro de comunicação com o WhatsApp.</td></tr><tr><td>2</td><td>101</td><td>EXPIRED</td><td>Mensagem expirada.</td></tr><tr><td>2</td><td>104</td><td>NOT_DELIVERED</td><td>Possíveis Causas: Limite atingido - muitos envios de mensagens tentados; Ou falha ao enviar mensagem porque o número de telefone de destino é parte de um experimento; Ou a estrutura do template não existe; Ou falhou ao enviar mensagem pois o número de destino está fora da janela de atendimento de 24h para receber mensagens de forma livre; Ou houve erro de upload de mídia (erro desconhecido); Ou falha ao enviar mensagem porque sua conta é inelegível no Facebook Business Manager; Ou houve falha temporária de upload. Tente novamente mais tarde.</td></tr><tr><td>2</td><td>105</td><td>WA_MO_MEDIA_UNRETRYABLE_EXCEPTION</td><td></td></tr><tr><td>202</td><td></td><td>EXPIREDINVALID_DESTINATION_NUMBER</td><td>Contato de WhatsApp inválido.</td></tr><tr><td>204</td><td></td><td>DESTINATION_BLOCKED_BY_OPTOUT</td><td>Destino bloqueado por Opt-Out.</td></tr><tr><td>207</td><td></td><td>INVALID_MESSAGE_TEXT</td><td>Valor de parâmetro inválido.</td></tr><tr><td>209</td><td></td><td>INVALID_CONTENT</td><td>Tipo de mensagem UNKNOWN inválido.</td></tr><tr><td>210</td><td></td><td>INVALID_SESSION</td><td>Sessão ou janela de atendimento não está aberta e nenhum Template de fallback está configurado.</td></tr><tr><td>301</td><td></td><td>INTERNAL_ERROR</td><td>Não foi possível verificar o contato na API do WhatsApp.</td></tr></tbody></table>

### Erros <a href="#erros" id="erros"></a>

<table data-header-hidden><thead><tr><th width="210"></th><th></th></tr></thead><tbody><tr><td><strong>HTTP Code</strong></td><td><strong>Description</strong></td></tr><tr><td>2xx</td><td>Success</td></tr><tr><td>200</td><td>Success (OK)</td></tr><tr><td>201</td><td>Successfully created (For POST requests)</td></tr><tr><td>302</td><td>Found</td></tr><tr><td>4xx</td><td>Client Errors</td></tr><tr><td>400</td><td>Request was invalid</td></tr><tr><td>401</td><td>Unauthorized</td></tr><tr><td>403</td><td>Forbidden</td></tr><tr><td>404</td><td>Not found</td></tr><tr><td>405</td><td>Method not allowed</td></tr><tr><td>412</td><td>Precondition failed</td></tr><tr><td>429</td><td>Too many requests</td></tr><tr><td>5xx</td><td>Server Errors</td></tr><tr><td>500</td><td>Internal server error</td></tr><tr><td>504</td><td>Timeout</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-pt.sinch.com/documentacao-tecnica-whatsapp/documentacao-tecnica-whatsapp/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.