# Subscrições a webhooks

## Processo

Este método envolve assinar um endpoint seu ao nosso webhook, para que sempre que houver uma mudança de estado dentro da plataforma, nós chamaremos esse endpoint para informá-lo da mudança. Dentro desse endpoint, você precisará interpretar o payload enviado por nós e atualizar o estado dentro do seu sistema.

<figure><img src="/files/bkHCL2OHUxZCIcxnYJqj" alt=""><figcaption><p>Webhook</p></figcaption></figure>

## Configuração

Para este ponto, você deve ter sua tabela pronta com os estados equivalentes do Shippify em sua plataforma. Se ainda não a tiver, acesse este link para elaborá-la. Para cada estado que precisar atualizar em sua plataforma, você terá que criar um webhook diferente seguindo os passos fornecidos:

### <img src="https://docs.shippify.co/~gitbook/image?url=https:%2F%2F4161681308-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F5jRdo0cXdFHp6c7ZKdof%252Fuploads%252FhWClN6JV7cXBYhVcj1pR%252Fimage.png%3Falt=media%26token=9350f3ef-438f-4f9b-98d7-a5aee121a635&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=81abe1a352ece75b5a48782ac8c87cbe6a162f25f58f894d8bd446f069ab2e95" alt="" data-size="line">Criar un Webhook <a href="#declarar-un-webhook" id="declarar-un-webhook"></a>

Em sua conta do Shippify, vá para o menu à esquerda, escolha a seção de Automatizações, procure por "Enviar Webhook" no menu lateral esquerdo ou entre diretamente por este link e clique no botão "CRIAR AUTOMATIZAÇÃO +".

<figure><img src="/files/KksWx82dk2rMiOgRssbf" alt=""><figcaption><p>Automatización</p></figcaption></figure>

### <img src="https://docs.shippify.co/~gitbook/image?url=https:%2F%2F4161681308-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F5jRdo0cXdFHp6c7ZKdof%252Fuploads%252FgCi3BsNsKouEfcSbJVuf%252Fimage.png%3Falt=media%26token=fa47692d-7d0a-44fb-bdb4-0d3df3b8cd9b&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=82ce46542d7384ac869937c9f28ab968f7d0540f5b358cf5cd02b4e0862be9c7" alt="" data-size="line">Configurar Trigger

Escolha as regras para a execução da sua automação. Você precisa selecionar o escopo no qual a automação funcionará, o evento que ativará a automação e condições adicionais, se necessário.&#x20;

Para o nosso caso, a entidade que vamos escolher é uma entrega e o evento é o estado para o qual você deseja enviar a atualização. No caso de você ter definido um motivo de problema de entrega ou uma etiqueta adicional em sua tabela, você deve adicionar esses dados como condições.

<figure><img src="/files/zjXTktG6pT0l6MKokfsH" alt=""><figcaption><p>Configuración</p></figcaption></figure>

### <img src="https://docs.shippify.co/~gitbook/image?url=https:%2F%2F4161681308-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F5jRdo0cXdFHp6c7ZKdof%252Fuploads%252FPEAUzv8vkHU8gh7zofEU%252Fimage.png%3Falt=media%26token=72874e0e-a741-4087-bf43-67ad7fef7ed5&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=6227089c582e7089a98f4281c1da3b6ab1c7f502816c725f7da3e8568c3eebc7" alt="" data-size="line">Configurar Webhook

Nesta etapa, você precisa adicionar as informações do endpoint onde as notificações serão recebidas e configurar se deseja enviar dados adicionais.

<figure><img src="/files/rXUmFegpw1tMYN0yFcBW" alt=""><figcaption><p>Configuración</p></figcaption></figure>

Define os parâmetros necessários para sua Automatização de Webhook.

<table><thead><tr><th width="211">Parâmetro</th><th>Descrição</th><th width="144" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>Webhook</td><td>URL para a qual o payload do evento será enviado.</td><td>true</td></tr><tr><td>Método HTTP</td><td>Método de solicitação HTTP para enviar o payload.</td><td>true</td></tr><tr><td>Prova de entrega</td><td>Em caso de o evento ter imagens anexadas, escolha se deseja adicioná-las no seu payload como imagens. <em><mark style="color:blue;">(Array[])</mark></em>. </td><td>false</td></tr><tr><td>HTTP Headers</td><td>Headers personalizados para a solicitação HTTP.</td><td>false</td></tr><tr><td>Assinatura do destinatário</td><td>Anexa a assinatura do destinatário como uma imagem PNG com fundo transparente. Ele é adicionado ao payload como 'signature'. <em><mark style="color:blue;">(String)</mark></em></td><td>false</td></tr><tr><td>Formato Base64</td><td>As imagens da prova de entrega ou assinatura são enviadas no formato base64. (Se não for marcado, então é uma URL).</td><td>false</td></tr><tr><td>URL de rastreamento</td><td>Inclui URL privada de rastreamento da entrega. Você a encontrará no payload como trackingUrl. <em><mark style="color:blue;">(String)</mark></em> </td><td>false</td></tr></tbody></table>

Depois de configurar, clique em criar. Opcionalmente, você pode adicionar um nome. A partir desse momento, sempre que os eventos e condições forem atendidos, nós chamaremos seu endpoint notificando o evento.

### Payload

O payload enviado para o webhook é extenso e contém muitas informações. Abaixo, mostraremos o significado de cada propriedade.

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

<pre class="language-json" data-full-width="true"><code class="lang-json"><strong>{
</strong>    "id": "t-xyz-123",
    "routeId": null,
    "networkId": 25,
    "networkName": "Default-company test",
    "jobId": null,
    "blocked": false,
    "cityId": 2,
    "cityName": "Guayaquil",
    "cityLang": "es",
    "companyId": 1,
    "companyName": "company test",
    "companyPlanType": "postpaid",
    "companyParentId": 1,
    "companyMode": 1,
    "shipperId": null,
    "shipperMobile": null,
    "type": "slot",
    "vehicleCapacity": 3,
    "vehicleId": null,
    "price": 0,
    "insurance": 0,
    "scheduledStartPickingDate": "2024-01-08T17:27:20.000Z",
    "scheduledEndPickingDate": "2024-01-08T17:57:20.000Z",
    "effectivePickupDate": "2024-01-08T16:33:44.000Z",
    "arrivalPickupDate": null,
    "scheduledStartDeliveryDate": "2024-01-08T18:12:20.000Z",
    "scheduledEndDeliveryDate": "2024-01-08T18:42:20.000Z",
    "effectiveDeliveryDate": "2024-01-08T17:27:07.000Z",
    "arrivalDeliveryDate": null,
    "creationDate": "2024-01-08T16:27:21.000Z",
    "pickupDueDate": null,
    "deliveryDueDate": null,
    "pickingPlace":{
      "lat": -2.1594806,
      "lng": -79.895742599,
      "originalAddress": "torres del norte, av. 9, guayaquil 090512, ecuador",
      "address": "torres del norte, av. 9, guayaquil 090512, ecuador"
    },
    "droppingPlace":{
      "lat": -2.1693477,
      "lng": -79.8985397,
      "originalAddress": "san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador",
      "address": "san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador"
    },
    "recipientInfo":{
      "name": "Test recipient",
      "email": "testrecip@test.com"
    },
    "senderInfo":{
      "name": "Test sender",
      "email": "testsender@test.com"
    },
    "senderInfoDecoded": {
        "name": "Test sender",
        "email": "testsender@test.com"
    },
    "receiverInfoDecoded": {
        "name": "Test recipient",
        "email": "testrecip@test.com"
    },
    "state": 7,
    "tags": ["delicado"],
    "items": [
        {
            "id": "Caja-12",
            "uuid": "bb3ef06e-647d-412b-92d1-293de6f5ce76",
            "name": "caixa",
            "size": "S",
            "price": 0,
            "weight": 0,
            "pickedUp": true,
            "delivered": true,
            "sid": "t-shippify2-40254_3",
            "scanned": false,
            "qty": 62
        }
    ],
    "referenceId": "test1234",
    "notes": "{\"comment\":\"test\"}",
    "attempts": 0,
    "countryCode": "EC",
    "countryName": "ECUADOR",
    "currencyCode": "USD",
    "formulaId": "1234",
    "cash": 0,
    "distance": 305.6000061035156,
    "distanceRoute": 0,
    "distanceCharged": 0,
    "totalPackagePrice": 0,
    "eventEntity": "delivery",
    "eventDate": "2024-01-08T17:27:08+00:00",
    "lastEventParams": {
        "author": {
            "type": "client",
            "id": 2534,
            "name": "Denny K. Saas",
            "email": "denny2@shippify.co"
        },
        "method": "UPDATE_ROUTE_STATUS",
        "timestamp": 1704734827
    },
    "colleted": 0,
    "paid": 0,
    "statusUpdateDate": null,
    "partial": 0,
    "notesJson": {
        "reason": "ADDRESS NOT FOUND, NEED CHANGE",
        "reasonId": 11,
        "comment": "test"
    },
    "itemsNumber": 62,
    "itemsWeight": 0,
    "itemsPrice": 0,
    "references": [],
    "incidences": [],
    "cityDepartment": null,
    "metadata": {
        "previousStatus": "processing"
    },
    "previousStatus": "processing",
    "dbId": 948182094,
    "eventType": "DELIVERY_COMPLETED",
    "eventAuthor": {
        "type": "client",
        "id": 2534,
        "name": "Denny K. Saas",
        "email": "denny2@shippify.co"
    },
    "eventCreatedAt": "2024-01-08 17:27:07",
    "eventDescription": "Delivery was completed (previous status was processing)",
    "eventParams": "{\"method\":\"UPDATE_ROUTE_STATUS\"}",
    "status": "completed",
    "eventId": 1704734828038,
    "images": ["https://cdn.dev.shippify.co/delivery-files/77030821377477563003dde3ce5.jpg"],
    "signature": "https://cdn.dev.shippify.co/delivery-files/16839098636794LPh1Zd7S5Goc9BvmQyG7BpT6asb.png",
    "trackingUrl": "https://api.shippify.co/track/t-xyz-123?token={token}"

}
</code></pre>

{% endtab %}

{% tab title="DETALLE" %}

<table><thead><tr><th width="262">Propiedad</th><th>Detalle</th></tr></thead><tbody><tr><td>id</td><td>Identificador de la entrega</td></tr><tr><td>routeId</td><td>Identificador de la ruta</td></tr><tr><td>networkId</td><td>Identificador de la red de conductores</td></tr><tr><td>networkName</td><td>Nombre de la red de conductores</td></tr><tr><td>cityId</td><td>Identificador de la ciudad de recolección</td></tr><tr><td>cityName</td><td>Nombre de la ciudad de recolección</td></tr><tr><td>cityLang</td><td>Idioma de la ciudad de recolección</td></tr><tr><td>jobId</td><td>Identificador del proceso actual, null si no tiene proceso</td></tr><tr><td>blocked</td><td>Indica si la tarea esta bloqueada</td></tr><tr><td>companyId</td><td>Identificador de la compañía de la entrega</td></tr><tr><td>companyName</td><td>Nombre de la compañía de la entrega</td></tr><tr><td>companyPlanType</td><td>Plan de la compañía de la entrega (pre o post pago)</td></tr><tr><td>companyParentId</td><td>Identificador de la compañía padre de la entrega</td></tr><tr><td>companyMode</td><td>Tipo de compañía: 1 basica, 2 saas</td></tr><tr><td>shipperId</td><td>Identificador del conductor que realiza la entrega</td></tr><tr><td>shipperMobile</td><td>Número telefónico del conductor que realiza la entrega</td></tr><tr><td>type</td><td>Tipo de la entrega: flex, express o regular</td></tr><tr><td>vehicleCapacity</td><td>Capacidad del vehiculo 1-5 bicicleta-camion</td></tr><tr><td>vehicleId</td><td>Identificador del vehiculo</td></tr><tr><td>price</td><td>Precio de la entrega</td></tr><tr><td>insurance</td><td>Seguro de la entrega</td></tr><tr><td>scheduledStartPickingDate</td><td>Fecha estimada de inicio de recolección</td></tr><tr><td>scheduledEndPickingDate</td><td>Fecha  estimada de final de recolección</td></tr><tr><td>effectivePickupDate</td><td>Fecha real de recolección</td></tr><tr><td>arrivalPickupDate</td><td>Fecha cuando el conductor llega al punto de recolección</td></tr><tr><td>scheduledStartDeliveryDate</td><td>Fecha estimada de inicio de etrega</td></tr><tr><td>scheduledEndDeliveryDate</td><td>Fecha  estimada de final de entrega</td></tr><tr><td>effectiveDeliveryDate</td><td>Fecha real de entrega</td></tr><tr><td>arrivalDeliveryDate</td><td>Fecha cuando el conductor llega al punto de entrega</td></tr><tr><td>creationDate</td><td>Fecha de creación de la entrega</td></tr><tr><td>pickupDueDate</td><td>Fecha máxima de recolección</td></tr><tr><td>deliveryDueDate</td><td>Fecha máxima de entrega</td></tr><tr><td>pickingPlace</td><td>Información de recolección</td></tr><tr><td>pickingPlace.lat</td><td>Latitud del punto de recolección</td></tr><tr><td>pickingPlace.lng</td><td>Longitud del punto de recolección</td></tr><tr><td>pickingPlace.originalAddress</td><td>Dirección de recolección enviada por integración</td></tr><tr><td>pickingPlace.address</td><td>Dirección de recolección corregida por google</td></tr><tr><td>droppingPlace</td><td>Información de entrega</td></tr><tr><td>droppingPlace.lat</td><td>Latitud del punto de entrega</td></tr><tr><td>droppingPlace.lng</td><td>Longitud del punto de entrega</td></tr><tr><td>droppingPlace.originalAddress</td><td>Dirección de entrega enviada por integración</td></tr><tr><td>droppingPlace.address</td><td>Dirección de entrega corregida por google</td></tr><tr><td>recipientInfo</td><td>Información de la persona que va a recibir la entrega</td></tr><tr><td>senderInfo</td><td>Información de la persona que va a enviar la entrega</td></tr><tr><td>state</td><td>Código del estado de la entrega</td></tr><tr><td>tags</td><td>Etiquetas digitales de la entrega</td></tr><tr><td>items</td><td>Información de los paquetes de la entrega</td></tr><tr><td>items.id</td><td>Identificador del paquete</td></tr><tr><td>items.name</td><td>Nombre del paquete</td></tr><tr><td>items.size</td><td>Tamaño del paquete</td></tr><tr><td>items.price</td><td>Precio del paquete</td></tr><tr><td>items.weight</td><td>Peso del paquete</td></tr><tr><td>items.pickedUp</td><td>Indica si ya fue recolectado el paquete</td></tr><tr><td>items.delivered</td><td>Indica si ya fue entregado el paquete</td></tr><tr><td>items.scanned</td><td>Indica si ya fue escaneado el paquete</td></tr><tr><td>items.qty</td><td>cantidad del paquete</td></tr><tr><td>referenceId</td><td>Identificador externo de la entrega.</td></tr><tr><td>notes</td><td>String con la razón del cambio de estado</td></tr><tr><td>attempts</td><td>Número de intentos de entrega</td></tr><tr><td>countryCode</td><td>Código del país</td></tr><tr><td>countryName</td><td>Nombre del país</td></tr><tr><td>currencyCode</td><td>Simbolo de la moneda en el país</td></tr><tr><td>formulaId</td><td>Identificador de la cuota aplicada</td></tr><tr><td>distance</td><td>Distancia entre el punto de recolección y el punto de entrega.</td></tr><tr><td>distanceRoute</td><td>Distancia entre el punto de entrega y el punta anterior en la ruta.</td></tr><tr><td>distanceCharged</td><td>Distancia cobrada</td></tr><tr><td>totalPackagePrice</td><td>Suma de los precios de los paquetes</td></tr><tr><td>eventEntity</td><td>Entidad bajo la cual se generó el evento</td></tr><tr><td>eventDate</td><td>Fecha en que se ejecutó el evento</td></tr><tr><td>lastEventParams</td><td>Información del author del evento </td></tr><tr><td>colleted</td><td>Indica si ya fue recolectado los paquetes</td></tr><tr><td>paid</td><td>Indica si ya fue pagada la entrega</td></tr><tr><td>notesJson</td><td>Objeto donde se guarda el motivo de cambio de estado.</td></tr><tr><td>notesJson.comment</td><td>Comentario general del cambio de estado</td></tr><tr><td>notesJson.reason</td><td>Razón del cambio de estado</td></tr><tr><td>notesJson.reasonId</td><td>Identificador de la razón</td></tr><tr><td>itemsNumber</td><td>Cantidad total de items en la entrega</td></tr><tr><td>itemsWeight</td><td>Peso total de la entrega</td></tr><tr><td>itemsPrice</td><td>Precio total de la de la entrega</td></tr><tr><td>references</td><td>Información adicional de la entrega</td></tr><tr><td>incidences</td><td>Incidencias de la entrega</td></tr><tr><td>metadata</td><td>Información adicional de la entrega</td></tr><tr><td>previousStatus</td><td>Estado anterior al actual</td></tr><tr><td>eventType</td><td>Tipo de evento</td></tr><tr><td>eventAuthor</td><td>Información del usuario que realizó el evento</td></tr><tr><td>eventCreatedAt</td><td>Fecha en que se creó el evento</td></tr><tr><td>eventDescription</td><td>Descripción del evento</td></tr><tr><td>eventParams</td><td>Parametros enviados al evento</td></tr><tr><td>status</td><td>Estado actual de la tarea</td></tr><tr><td>eventId</td><td>Identificador del evento</td></tr><tr><td>images</td><td>Arreglo de imágenes de las pruebas de entrega. Puede ser en url o en base64 según la configuración</td></tr><tr><td>signature</td><td>Adjunta la firma del destinatario como una imagen png con fondo transparente.Puede ser en url o en base64 según la configuración</td></tr><tr><td>trackingUrl</td><td>URL de seguimiento privada de la entrega.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Como testar o webhook?&#x20;

Uma vez que a automação é criada, você pode prosseguir para testá-la. Se você ainda não tem um endpoint pronto para receber atualizações, você pode usar um [endpoint de teste](https://webhook.site/#!/view/4ffe8bb1-eb10-4560-812a-fc7d0ee54c63/aa83de64-adbe-4923-ba2a-e404399a50bc/1) para testar a configuração do webhook e ver o payload. Para este exemplo, configuraremos a automação do webhook para enviar a atualização quando a entrega mudar para o status "Concluído".

<figure><img src="/files/SQHi34KueZKtDbFDx8Qo" alt=""><figcaption><p>Webhook</p></figcaption></figure>

1. Crie uma entrega [na Dash](https://dash.shippify.co/deliver) (se você já tiver criado uma, pode pular esta etapa).&#x20;
2. Altere o status conforme apropriado para a automação, neste caso, alteraremos o status para Concluído porque é assim que configuramos nossa automação de teste.

<figure><img src="/files/ZSR9hhpclWOa7skEDpud" alt=""><figcaption><p>Altere o status</p></figcaption></figure>

3. Observe o payload enviado para o webhook, neste caso usamos um [webhook de teste](https://webhook.site/#!/view/4ffe8bb1-eb10-4560-812a-fc7d0ee54c63/aa83de64-adbe-4923-ba2a-e404399a50bc/1) para podermos ver o payload enviado, caso você já tenha um endpoint configurado para receber notificações você pode colocar um log para identificar que a chamada foi feita.

<figure><img src="/files/AlSP2xwEldDxrE6H5MOM" alt=""><figcaption><p>Webhook de teste</p></figcaption></figure>

Dentro da automação, você pode ver as execuções com falha e bem-sucedidas da automação junto com o identificador da entrega associada. Neste caso, temos uma execução bem-sucedida para a entrega `t-pruaas-5104`.

<figure><img src="/files/XblrWwp9rTk5WxYEfFod" alt=""><figcaption><p>Execuções</p></figcaption></figure>

## Assinantes de erros&#x20;

Depois que o webhook for configurado com sucesso, as assinaturas de erro podem ser ativadas. Aqui você pode registrar um ou mais e-mails nos quais os alertas serão enviados sempre que uma notificação falhar ao ser enviada ou o endpoint responder com um erro.

<figure><img src="/files/8QSMTtVtt4hdTlSiggwi" alt=""><figcaption><p>Assinantes de erros</p></figcaption></figure>

<figure><img src="/files/T2IdmoYPFwuoiTTK7bJU" alt=""><figcaption><p>Email</p></figcaption></figure>

## Configuração personalizada

Se precisar usar o webhook, mas precisa receber um payload diferente do anterior, será necessário solicitar por e-mail, anexando o payload que deseja receber para cada estado e [a tabela com os estados equivalentes na Shippify](/developers/pt/guia-de-integracao/processos-basicos/atualizacao-de-estados/estados.md#enlace-de-estados-con-plataforma-externa).&#x20;

<details>

<summary>Exemplo de request</summary>

{% code overflow="wrap" %}

```
Bom dia,

Desejo atualizar os pedidos na minha plataforma através de um webhook com payload personalizado.

* Email da minha empresa na Shippify: example@shippify.co
* Tabela com os estados equivalentes no Shippify e os payloads personalizados: Documento anexo

Desde já agradeço,

Atenciosamente,
Name
```

{% endcode %}

</details>


---

# 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.shippify.co/developers/pt/guia-de-integracao/processos-basicos/atualizacao-de-estados/subscricoes-a-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.