Webhooks

The endpoints that receive events right away, signed with the Standard Webhooks spec, with retries, automatic disabling, redelivery and a test event.

GET/v1/webhooks— Registered endpoints
POST/v1/webhooks— Register an endpoint
PATCH/v1/webhooks/{webhookId}— Update an endpoint
DELETE/v1/webhooks/{webhookId}— Delete an endpoint
POST/v1/webhooks/{webhookId}/rotate-secret— Rotate the secret
POST/v1/webhooks/{webhookId}/test— Send a test event
GET/v1/webhooks/{webhookId}/deliveries— An endpoint's deliveries
POST/v1/webhooks/{webhookId}/deliveries/{deliveryId}/retry— Redeliver

Routes

GET/v1/webhooks

Registered endpoints

The account's webhook endpoints.

Permission: webhooks:manage

Response200OK

datalist of Webhookrequired: The endpoints.

Example

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

Errors for this route

And the errors common to every route

POST/v1/webhooks

HTTPS and public hosts only. The response carries the secret (whsec_…) ONCE — keep it: it is what you verify the signature with. This route does not accept Idempotency-Key (a stored response would keep the secret in plain text); repeating creates another endpoint.

Permission: webhooks:manage

Request body

urlstringrequired: The URL, HTTPS and public only. Credentials in the URL are refused.
typeslist of string: The types (absent = all the account can read).one of 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
descriptionstringnullable: Description.

Example body

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

Response201Created

dataWebhookrequired: The endpoint.
secretstringrequired: The secret, only in this response.

Example

curl -X POST 'https://api.imobyflow.com.br/v1/webhooks' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -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

Errors for this route

And the errors common to every route

PATCH/v1/webhooks/{webhookId}

Update an endpoint

Changes the URL, the types, the description — or disables and re-enables it (re-enabling clears the disable reason).

Permission: webhooks:manageSupports Idempotency-Key

Path parameters

webhookIdstringrequired: Endpoint id (wh_…).

Request body

urlstring: The URL.
typeslist of string: The types.one of 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
descriptionstringnullable: Description.
statusstring: ACTIVE re-enables (clears the disable reason) and DISABLED disables.one of ACTIVE DISABLED

Example body

{
  "status": "ACTIVE"
}

Response200OK

dataWebhookrequired: The endpoint.

Example

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

Errors for this route

And the errors common to every route

DELETE/v1/webhooks/{webhookId}

Delete an endpoint

Stops delivering and deletes the endpoint.

Permission: webhooks:manageSupports Idempotency-Key

Path parameters

webhookIdstringrequired: Endpoint id (wh_…).

Response200OK

dataWebhookrequired: The deleted endpoint.
resultobjectrequired: The outcome.
result.outcomestringrequired: DELETED.

Example

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

Errors for this route

And the errors common to every route

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

Rotate the secret

Generates a new secret, returned ONCE. The previous one keeps signing alongside for 24 hours — time to switch it in your system without losing events. No Idempotency-Key.

Permission: webhooks:manage

Path parameters

webhookIdstringrequired: Endpoint id (wh_…).

Response200OK

dataWebhookrequired: The endpoint.
secretstringrequired: The new secret.

Example

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

Errors for this route

404not_found

And the errors common to every route

POST/v1/webhooks/{webhookId}/test

Send a test event

Delivers a webhook.test NOW, signed, and returns what your system answered.

Permission: webhooks:manageSupports Idempotency-Key

Path parameters

webhookIdstringrequired: Endpoint id (wh_…).

Response200OK

dataWebhookTestResultrequired: The result.

Example

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

Errors for this route

And the errors common to every route

GET/v1/webhooks/{webhookId}/deliveries

An endpoint's deliveries

The deliveries, newest first, with status, attempts and the last status code.

Permission: webhooks:manage

Path parameters

webhookIdstringrequired: Endpoint id (wh_…).

Query parameters

limitinteger: Items per page: 1 to 200 (default 50).
cursorstring: The nextCursor from the previous page. The list is over when it comes back null. It is only valid for this route and this account.

Response200OK

datalist of Deliveryrequired: The deliveries.
nextCursorstringrequirednullable: Next page cursor (null = done).

Example

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

Errors for this route

And the errors common to every route

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

Redeliver

A new round of attempts for the same delivery — with the SAME webhook-id, so your system recognizes the repeat. One already scheduled returns ALREADY_SCHEDULED.

Permission: webhooks:manageSupports Idempotency-Key

Path parameters

webhookIdstringrequired: Endpoint id (wh_…).
deliveryIdstringrequired: Delivery id (dlv_…).

Response200OK

dataDeliveryrequired: The delivery.
resultobjectrequired: The outcome.
result.outcomestringrequired: SCHEDULED or ALREADY_SCHEDULED.one of SCHEDULED ALREADY_SCHEDULED

Example

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: en' \
  -H "Idempotency-Key: $(uuidgen)"

Errors for this route

And the errors common to every route

Objects

Webhook

A webhook endpoint. The secret never comes back here.

idstringrequired: Endpoint id (wh_…).
urlstringrequired: The URL (HTTPS only).
typeslist of stringrequired: The types it receives (empty = all the account can read).one of 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
descriptionstringrequirednullable: Description.
statusstringrequired: ACTIVE or DISABLED.one of ACTIVE DISABLED
disabledAtstringrequirednullable: When it was disabled.
disabledReasonstringrequirednullable: GONE_410 (your system answered 410), FAILURE_RATE (half or more of the deliveries failed in 48 h) or MANUAL.
secretRotatedAtstringrequirednullable: Last secret rotation.
previousSecretValidUntilstringrequirednullable: Until when the previous secret still signs alongside (24 h after rotation).
createdAtstringrequired: When it was created (UTC).
updatedAtstringrequired: Last change (UTC).

WebhookCreate

A new endpoint.

urlstringrequired: The URL, HTTPS and public only. Credentials in the URL are refused.
typeslist of string: The types (absent = all the account can read).one of 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
descriptionstringnullable: Description.

WebhookUpdate

What to change on the endpoint.

urlstring: The URL.
typeslist of string: The types.one of 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
descriptionstringnullable: Description.
statusstring: ACTIVE re-enables (clears the disable reason) and DISABLED disables.one of ACTIVE DISABLED

Delivery

One event delivery to an endpoint.

idstringrequired: Delivery id (dlv_…).
eventIdstringrequirednullable: The delivered event.
typestringrequirednullable: Event type.
statusstringrequired: PENDING, RETRYING, DELIVERED, FAILED (out of retries) or SKIPPED (the endpoint was disabled).
attemptsintegerrequired: Attempts made.
lastStatusCodeintegerrequirednullable: Last HTTP status from your system.
lastErrorstringrequirednullable: Last error.
lastAttemptAtstringrequirednullable: Last attempt.
nextAttemptAtstringrequirednullable: Next attempt (1 min, 5 min, 30 min, 2 h, 6 h and 12 h).
deliveredAtstringrequirednullable: When it was delivered.
createdAtstringrequirednullable: When the delivery was opened.

WebhookTestResult

The test event result (webhook.test).

deliveredbooleanrequired: Your system answered 2xx.
statusCodeintegerrequirednullable: The status it answered.
errorstringrequirednullable: The failure reason.
msintegerrequirednullable: Delivery time, in ms.