> For the complete documentation index, see [llms.txt](https://docs.shippify.co/developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shippify.co/developers/pt/guia-de-integracao/processos-basicos/atualizacao-de-estados/subscricoes-a-webhooks.md).

# 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>