Webhooks

Os endereços que recebem os eventos na hora, assinados no padrão Standard Webhooks, com nova tentativa, desligamento automático, reenvio e evento de teste.

GET/v1/webhooks— Endereços cadastrados
POST/v1/webhooks— Cadastrar um endereço
PATCH/v1/webhooks/{webhookId}— Alterar um endereço
DELETE/v1/webhooks/{webhookId}— Apagar um endereço
POST/v1/webhooks/{webhookId}/rotate-secret— Trocar o segredo
POST/v1/webhooks/{webhookId}/test— Mandar um evento de teste
GET/v1/webhooks/{webhookId}/deliveries— Entregas de um endereço
POST/v1/webhooks/{webhookId}/deliveries/{deliveryId}/retry— Reenviar uma entrega

As rotas

GET/v1/webhooks

Endereços cadastrados

Os endereços de webhook da conta.

Permissão: webhooks:manage

Resposta200OK

datalista de Webhookobrigatório: Os endereços.

Exemplo

curl -X GET 'https://api.imobyflow.com.br/v1/webhooks' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR'

Erros desta rota

E os erros comuns a toda rota

POST/v1/webhooks

Só HTTPS e só host público. A resposta traz o secret (whsec_…) UMA vez — guarde-o: é com ele que você confere a assinatura. Esta rota não aceita Idempotency-Key (a resposta guardada deixaria o segredo em texto); repetir cria outro endereço.

Permissão: webhooks:manage

Corpo do pedido

urlstringobrigatório: O endereço, só HTTPS e público. Credencial na URL é recusada.
typeslista de string: Os tipos (ausente = todos os que a conta lê).um de property.created property.updated property.deleted property.restored property.purged lead.created lead.updated lead.deleted lead.restored lead.purged radar.client_summary partnership.created partnership.updated captacao.offer_received captacao.offer_accepted captacao.offer_withdrawn
descriptionstringpode vir nulo: Descrição.

Exemplo de corpo

{
  "url": "https://crm.suaimobiliaria.com.br/imobyflow/eventos",
  "types": [
    "property.updated",
    "lead.created"
  ],
  "description": "CRM — produção"
}

Resposta201Criado

dataWebhookobrigatório: O endereço.
secretstringobrigatório: O segredo, só nesta resposta.

Exemplo

curl -X POST 'https://api.imobyflow.com.br/v1/webhooks' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "url": "https://crm.suaimobiliaria.com.br/imobyflow/eventos",
  "types": [
    "property.updated",
    "lead.created"
  ],
  "description": "CRM — produção"
}
JSON

Erros desta rota

E os erros comuns a toda rota

PATCH/v1/webhooks/{webhookId}

Alterar um endereço

Muda o endereço, os tipos, a descrição — ou desliga e religa (religar limpa o motivo do desligamento).

Permissão: webhooks:manageAceita Idempotency-Key

Parâmetros no caminho

webhookIdstringobrigatório: Id do endereço (wh_…).

Corpo do pedido

urlstring: O endereço.
typeslista de string: Os tipos.um de property.created property.updated property.deleted property.restored property.purged lead.created lead.updated lead.deleted lead.restored lead.purged radar.client_summary partnership.created partnership.updated captacao.offer_received captacao.offer_accepted captacao.offer_withdrawn
descriptionstringpode vir nulo: Descrição.
statusstring: ACTIVE religa (limpa o motivo do desligamento) e DISABLED desliga.um de ACTIVE DISABLED

Exemplo de corpo

{
  "status": "ACTIVE"
}

Resposta200OK

dataWebhookobrigatório: O endereço.

Exemplo

curl -X PATCH 'https://api.imobyflow.com.br/v1/webhooks/wh_9c8b7a6f5e4d3c2b' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "status": "ACTIVE"
}
JSON

Erros desta rota

E os erros comuns a toda rota

DELETE/v1/webhooks/{webhookId}

Apagar um endereço

Para de entregar e apaga o endereço.

Permissão: webhooks:manageAceita Idempotency-Key

Parâmetros no caminho

webhookIdstringobrigatório: Id do endereço (wh_…).

Resposta200OK

dataWebhookobrigatório: O endereço apagado.
resultobjetoobrigatório: O desfecho.
result.outcomestringobrigatório: DELETED.

Exemplo

curl -X DELETE 'https://api.imobyflow.com.br/v1/webhooks/wh_9c8b7a6f5e4d3c2b' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR' \
  -H "Idempotency-Key: $(uuidgen)"

Erros desta rota

E os erros comuns a toda rota

POST/v1/webhooks/{webhookId}/rotate-secret

Trocar o segredo

Gera um segredo novo, devolvido UMA vez. O anterior segue assinando junto por 24 horas — dá tempo de trocar no seu sistema sem perder evento. Sem Idempotency-Key.

Permissão: webhooks:manage

Parâmetros no caminho

webhookIdstringobrigatório: Id do endereço (wh_…).

Resposta200OK

dataWebhookobrigatório: O endereço.
secretstringobrigatório: O segredo novo.

Exemplo

curl -X POST 'https://api.imobyflow.com.br/v1/webhooks/wh_9c8b7a6f5e4d3c2b/rotate-secret' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR'

Erros desta rota

404not_found

E os erros comuns a toda rota

POST/v1/webhooks/{webhookId}/test

Mandar um evento de teste

Entrega um webhook.test AGORA, assinado, e devolve o que o seu sistema respondeu.

Permissão: webhooks:manageAceita Idempotency-Key

Parâmetros no caminho

webhookIdstringobrigatório: Id do endereço (wh_…).

Resposta200OK

dataWebhookTestResultobrigatório: O resultado.

Exemplo

curl -X POST 'https://api.imobyflow.com.br/v1/webhooks/wh_9c8b7a6f5e4d3c2b/test' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR' \
  -H "Idempotency-Key: $(uuidgen)"

Erros desta rota

E os erros comuns a toda rota

GET/v1/webhooks/{webhookId}/deliveries

Entregas de um endereço

As entregas, mais novas antes, com o status, as tentativas e o último código.

Permissão: webhooks:manage

Parâmetros no caminho

webhookIdstringobrigatório: Id do endereço (wh_…).

Filtros e paginação

limitinteger: Itens por página: de 1 a 200 (padrão 50).
cursorstring: O nextCursor da página anterior. A lista acabou quando ele vem nulo. Ele vale só para esta rota e esta conta.

Resposta200OK

datalista de Deliveryobrigatório: As entregas.
nextCursorstringobrigatóriopode vir nulo: Cursor da próxima página (nulo = acabou).

Exemplo

curl -X GET 'https://api.imobyflow.com.br/v1/webhooks/wh_9c8b7a6f5e4d3c2b/deliveries' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR'

Erros desta rota

E os erros comuns a toda rota

POST/v1/webhooks/{webhookId}/deliveries/{deliveryId}/retry

Reenviar uma entrega

Uma nova rodada de tentativas para a mesma entrega — com o MESMO webhook-id, então o seu sistema reconhece a repetição. A que já está agendada responde ALREADY_SCHEDULED.

Permissão: webhooks:manageAceita Idempotency-Key

Parâmetros no caminho

webhookIdstringobrigatório: Id do endereço (wh_…).
deliveryIdstringobrigatório: Id da entrega (dlv_…).

Resposta200OK

dataDeliveryobrigatório: A entrega.
resultobjetoobrigatório: O desfecho.
result.outcomestringobrigatório: SCHEDULED ou ALREADY_SCHEDULED.um de SCHEDULED ALREADY_SCHEDULED

Exemplo

curl -X POST 'https://api.imobyflow.com.br/v1/webhooks/wh_9c8b7a6f5e4d3c2b/deliveries/dlv_20261002164512000_evt_4f1c9a7e2b3d8c6a5e4f1b2c/retry' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR' \
  -H "Idempotency-Key: $(uuidgen)"

Erros desta rota

E os erros comuns a toda rota

Os objetos

Webhook

Um endereço de webhook. O segredo nunca sai aqui.

idstringobrigatório: Id do endereço (wh_…).
urlstringobrigatório: O endereço (só HTTPS).
typeslista de stringobrigatório: Os tipos que ele recebe (vazio = todos os que a conta lê).um de property.created property.updated property.deleted property.restored property.purged lead.created lead.updated lead.deleted lead.restored lead.purged radar.client_summary partnership.created partnership.updated captacao.offer_received captacao.offer_accepted captacao.offer_withdrawn
descriptionstringobrigatóriopode vir nulo: Descrição.
statusstringobrigatório: ACTIVE ou DISABLED.um de ACTIVE DISABLED
disabledAtstringobrigatóriopode vir nulo: Quando foi desligado.
disabledReasonstringobrigatóriopode vir nulo: GONE_410 (o seu sistema respondeu 410), FAILURE_RATE (metade ou mais das entregas falhou em 48 h) ou MANUAL.
secretRotatedAtstringobrigatóriopode vir nulo: Última troca do segredo.
previousSecretValidUntilstringobrigatóriopode vir nulo: Até quando o segredo anterior ainda assina junto (24 h depois da troca).
createdAtstringobrigatório: Quando foi criado (UTC).
updatedAtstringobrigatório: Última alteração (UTC).

WebhookCreate

Um endereço novo.

urlstringobrigatório: O endereço, só HTTPS e público. Credencial na URL é recusada.
typeslista de string: Os tipos (ausente = todos os que a conta lê).um de property.created property.updated property.deleted property.restored property.purged lead.created lead.updated lead.deleted lead.restored lead.purged radar.client_summary partnership.created partnership.updated captacao.offer_received captacao.offer_accepted captacao.offer_withdrawn
descriptionstringpode vir nulo: Descrição.

WebhookUpdate

O que mudar no endereço.

urlstring: O endereço.
typeslista de string: Os tipos.um de property.created property.updated property.deleted property.restored property.purged lead.created lead.updated lead.deleted lead.restored lead.purged radar.client_summary partnership.created partnership.updated captacao.offer_received captacao.offer_accepted captacao.offer_withdrawn
descriptionstringpode vir nulo: Descrição.
statusstring: ACTIVE religa (limpa o motivo do desligamento) e DISABLED desliga.um de ACTIVE DISABLED

Delivery

Uma entrega de evento a um endereço.

idstringobrigatório: Id da entrega (dlv_…).
eventIdstringobrigatóriopode vir nulo: O evento entregue.
typestringobrigatóriopode vir nulo: Tipo do evento.
statusstringobrigatório: PENDING, RETRYING, DELIVERED, FAILED (esgotou as tentativas) ou SKIPPED (o endereço estava desligado).
attemptsintegerobrigatório: Tentativas feitas.
lastStatusCodeintegerobrigatóriopode vir nulo: Último código HTTP do seu sistema.
lastErrorstringobrigatóriopode vir nulo: Último erro.
lastAttemptAtstringobrigatóriopode vir nulo: Última tentativa.
nextAttemptAtstringobrigatóriopode vir nulo: Próxima tentativa (1 min, 5 min, 30 min, 2 h, 6 h e 12 h).
deliveredAtstringobrigatóriopode vir nulo: Quando foi entregue.
createdAtstringobrigatóriopode vir nulo: Quando a entrega foi aberta.

WebhookTestResult

O resultado do evento de teste (webhook.test).

deliveredbooleanobrigatório: O seu sistema respondeu 2xx.
statusCodeintegerobrigatóriopode vir nulo: O código que ele respondeu.
errorstringobrigatóriopode vir nulo: O motivo da falha.
msintegerobrigatóriopode vir nulo: Tempo da entrega, em ms.