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.

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:

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 +".

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.

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.

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

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

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.

{
    "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}"

}

Como testar o webhook?

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 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".

Crie uma entrega na Dash (se você já tiver criado uma, pode pular esta etapa).
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.

Observe o payload enviado para o webhook, neste caso usamos um webhook de teste 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.

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.

Assinantes de erros

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.

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.

Exemplo de request

Bom dia,

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

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

Desde já agradeço,

Atenciosamente,
Iliana Bolaños