Webhook de armazenamento

O escopo storage envia eventos de arquivos e pastas no armazenamento da conta. Use este webhook para sincronizar criação de pastas, criação de registros de arquivo, upload concluído, renomeação, exclusão e falhas de exclusão.

Visão geral de webhooks

Consulte o contrato base, headers, assinatura e recomendações gerais de entrega.

Eventos disponíveis

Evento	Quando é enviado
`storage.folder.created`	Pasta criada.
`storage.folder.renamed`	Pasta renomeada.
`storage.folder.deleted`	Pasta excluída.
`storage.folder.delete_failed`	Exclusão de pasta falhou parcial ou totalmente.
`storage.file.created`	Registro de arquivo criado e aguardando upload.
`storage.file.uploaded`	Arquivo enviado e armazenado com sucesso.
`storage.file.renamed`	Arquivo renomeado.
`storage.file.deleted`	Arquivo excluído.
`storage.file.delete_failed`	Exclusão de arquivo falhou.

storage.file.created indica que a assinatura de upload foi gerada e o registro está aguardando envio. O arquivo só está disponível após storage.file.uploaded.

Payload de arquivo enviado

{
  "id": "evt_71fdf700-e01b-458c-bdbc-f53607f5d75e",
  "event": "storage.file.uploaded",
  "scope": "storage",
  "created_at": "2026-06-23T12:30:00Z",
  "data": {
    "item": {
      "id": "file_9fcb573b",
      "type": "file",
      "name": "contrato.pdf",
      "parent_id": "folder_a879e42a",
      "extension": "pdf",
      "content_type": "application/pdf",
      "size": 842100,
      "status": "uploaded",
      "uploaded_at": "2026-06-23T12:30:00Z",
      "created_at": "2026-06-23T12:29:30Z",
      "updated_at": "2026-06-23T12:30:00Z"
    }
  }
}

Payload de pasta criada

{
  "id": "evt_17ef15ef-033d-4f68-99c8-4d98dd744ed9",
  "event": "storage.folder.created",
  "scope": "storage",
  "created_at": "2026-06-23T12:28:00Z",
  "data": {
    "item": {
      "id": "folder_a879e42a",
      "type": "folder",
      "name": "Contratos",
      "parent_id": null,
      "created_at": "2026-06-23T12:28:00Z",
      "updated_at": "2026-06-23T12:28:00Z"
    }
  }
}

Campos de `data.item`

Campos comuns:

Campo	Tipo	Descrição
`id`	`string`	ID do item.
`type`	`string`	`file` ou `folder`.
`name`	`string`	Nome do item.
`parent_id`	`string` ou `null`	ID da pasta pai.
`created_at`	`string`	Data de criação em ISO 8601.
`updated_at`	`string`	Data da última atualização em ISO 8601.

Campos adicionais para arquivos:

Campo	Tipo	Descrição
`extension`	`string`	Extensão do arquivo.
`content_type`	`string`	MIME type do arquivo.
`size`	`integer`	Tamanho em bytes.
`status`	`string`	Status do arquivo.
`uploaded_at`	`string`	Data de upload, quando disponível.

Campos extras por evento

Evento	Campos extras
`storage.folder.renamed`	`old_name`, `new_name`.
`storage.file.renamed`	`old_name`, `new_name`.
`storage.folder.deleted`	`files_count`, `failed_files_count`.
`storage.folder.delete_failed`	`files_count`, `failed_files_count`.
`storage.file.deleted`	`failed_keys_count`.
`storage.file.delete_failed`	`failed_keys_count`.

Exemplo de renomeação

{
  "id": "evt_13e3d6a5-3ed6-4453-9b77-42c66d6c8bdf",
  "event": "storage.folder.renamed",
  "scope": "storage",
  "created_at": "2026-06-23T12:31:00Z",
  "data": {
    "item": {
      "id": "folder_a879e42a",
      "type": "folder",
      "name": "Contratos 2026",
      "parent_id": null,
      "created_at": "2026-06-23T12:28:00Z",
      "updated_at": "2026-06-23T12:31:00Z"
    },
    "old_name": "Contratos",
    "new_name": "Contratos 2026"
  }
}

Exemplo de falha de exclusão

{
  "id": "evt_6429e6bc-1360-48a8-aabf-6be125f084b0",
  "event": "storage.folder.delete_failed",
  "scope": "storage",
  "created_at": "2026-06-23T12:40:00Z",
  "data": {
    "item": {
      "id": "folder_a879e42a",
      "type": "folder",
      "name": "Contratos 2026",
      "parent_id": null,
      "created_at": "2026-06-23T12:28:00Z",
      "updated_at": "2026-06-23T12:40:00Z"
    },
    "files_count": 12,
    "failed_files_count": 1
  }
}

Como consumir

Use data.item.id e data.item.type para correlacionar o item.
Trate storage.file.created como estado de preparação de upload.
Trate storage.file.uploaded como confirmação de arquivo disponível.
Em eventos de renomeação, use old_name e new_name.
Em falhas de exclusão, revise os contadores e consulte o painel se precisar de detalhe operacional.

O webhook não inclui link público do arquivo. Use os endpoints ou telas de armazenamento para acessar ou baixar arquivos conforme as permissões da conta.

Primeiros passos

Utilidades

Funcionalidades

Webhook

Webhook de armazenamento

Visão geral de webhooks

Eventos disponíveis

Payload de arquivo enviado

Payload de pasta criada

Campos de `data.item`

Campos extras por evento

Exemplo de renomeação

Exemplo de falha de exclusão

Como consumir

Relacionado

Visão geral

Armazenamento

Visão geral de webhooks

​Eventos disponíveis

​Payload de arquivo enviado

​Payload de pasta criada

​Campos de data.item

​Campos extras por evento

​Exemplo de renomeação

​Exemplo de falha de exclusão

​Como consumir

​Relacionado

Visão geral

Armazenamento

Eventos disponíveis

Payload de arquivo enviado

Payload de pasta criada

Campos de `data.item`

Campos extras por evento

Exemplo de renomeação

Exemplo de falha de exclusão

Como consumir

Relacionado