Webhooks 101: como a LotShow API avisa que uma foto está pronta

Uma foto de estúdio leva um tempinho para ficar pronta. O seu sistema poderia perguntar ao LotShow a cada poucos segundos se já terminou, ou o LotShow pode avisar o seu sistema no momento em que terminar. Esse segundo jeito é um webhook, e é assim que a LotShow API entrega os resultados.

Polling ou webhooks

Polling significa que o seu código chama GET /v1/jobs/{id} em intervalos até o status mudar. Funciona, mas a maioria dessas chamadas volta sem nada de novo, e quanto mais carros você processa, mais chamadas você faz.

Um webhook inverte isso. Ao criar um job, você passa uma URL ao LotShow. Quando o job termina, o LotShow envia um POST HTTPS para essa URL com o resultado. O seu sistema não faz nada até haver algo a fazer.

Os eventos

• job.completed: uma foto de estúdio está pronta, com a URL da imagem final.
• job.failed: uma foto não pôde ser concluída, e o crédito foi reembolsado.
• credits.low: o seu saldo compartilhado ficou abaixo de 20 créditos.

Você escolhe quais eventos cada endpoint recebe, para que um sistema de estoque escute as fotos prontas enquanto uma ferramenta de faturamento só fica sabendo dos saldos baixos.

Como é uma entrega

Um job concluído chega como um pequeno corpo JSON:

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:41:40.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "white-hall",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

O id é o id do job que você recebeu ao criá-lo. Por isso vale a pena guardar o id do job junto ao número de estoque no seu próprio sistema: o webhook diz qual job terminou, e os seus registros dizem a qual carro ele pertence.

Construindo um bom endpoint

1. Responda rápido. Devolva um status 2xx assim que o evento chegar e faça o trabalho de verdade, como baixar a imagem, em segundo plano.
2. Espere repetições. Uma entrega pode chegar mais de uma vez, por exemplo depois de um timeout, porque o LotShow tenta de novo até o seu endpoint responder. Verifique se você já tratou um evento antes de agir sobre ele de novo.
3. Não conte com a ordem. Dois jobs enviados com um segundo de diferença podem terminar em qualquer ordem. Associe os resultados pelo id do job, não pela hora de chegada.
4. Confira a assinatura. Toda entrega é assinada com o segredo de assinatura da sua conta, que fica em Configurações, nos cabeçalhos webhook-id, webhook-timestamp e webhook-signature (o esquema Standard Webhooks). Rejeite tudo o que não passar na verificação.
5. Registre tudo. Guarde o corpo bruto e a hora de cada entrega. Quando algo parecer errado, o log é o primeiro lugar onde você vai olhar.

Testando antes de ir ao ar

Cada endpoint em Configurações tem um botão Enviar teste, e a API tem POST /v1/webhooks/{id}/test. Os dois enviam um evento de exemplo para o seu endpoint, para você testar o seu handler sem gastar créditos. Um inspetor de requisições ou um túnel local é uma boa forma de ver exatamente o que o seu endpoint recebe.

Pronto para começar? As chaves de API vêm com Pro e Elite: crie uma em Configurações, em Chaves de API.