Endpoints de automação, lotes e webhooks

Estas 20 operações estão em homologação em https://api.staging.agilink.io/v1. Exemplos usam recursos fictícios. A referência interativa contém os schemas completos de cada campo, inclusive objetos internos. Leia também o guia da integração e a migração de tokens.

Todas as requisições usam Authorization: Bearer <credencial>. Sessão humana e chave limitada são indicadas por operação. OAuth depende da Tarefa 2. Mutações exigem Idempotency-Key; atualizações e exclusões exigem If-Match. Downloads devolvem JSON/CSV; o relatório de importação aceita format=csv. Nunca envie credenciais em query strings.

POST /exports

Solicitar exportação de links, eventos ou relatórios.

Permissão: exports:create. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
appId	AppId	sim	Consulte o schema para restrições e campos internos
dataset	links / events / summary	sim	Valores: links, events, summary
format	csv / json	sim	Valores: csv, json
filters	object	não	Consulte o schema para restrições e campos internos

{
  "appId": "app_loja",
  "dataset": "links",
  "format": "json"
}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/exports' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","dataset":"links","format":"json"}'

Resposta: 202. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso a acompanhar.	/v1/operations/b0000000-0000-4000-8000-000000000001
Retry-After	Segundos até a próxima consulta.	1

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "kind": "export",
    "state": "queued",
    "operationId": "b0000000-0000-4000-8000-000000000001",
    "revision": "20000000-0000-4000-8000-000000000001",
    "total": 1,
    "succeeded": 0,
    "failed": 0,
    "expiresAt": "2026-10-27T01:00:00Z",
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z",
    "downloadUrl": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /exports/{exportId}

Consultar progresso, expiração e metadados.

Permissão: exports:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
exportId	path	sim	OpaqueId

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/exports/b0000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "kind": "batch",
    "state": "queued",
    "operationId": "b0000000-0000-4000-8000-000000000001",
    "revision": "20000000-0000-4000-8000-000000000001",
    "total": 1,
    "succeeded": 0,
    "failed": 0,
    "expiresAt": "2026-10-27T01:00:00Z",
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z",
    "downloadUrl": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /exports/{exportId}/download

Download autorizado ou URL temporária conforme política.

Permissão: exports:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
exportId	path	sim	OpaqueId

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/exports/b0000000-0000-4000-8000-000000000001/download' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Download autenticado, expira em 24 horas, máximo 1000 registros / 1 MiB; CSV neutraliza fórmulas.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

Resposta de arquivo JSON ou CSV. Use –output export.json ou export.csv no cURL e confira Content-Type. Download exige autenticação e leitura do conjunto original; expira em 24 horas.

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /link-batches

Criação/edição/movimentação/arquivamento/remoção em lote.

Permissão: batches:create. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
appId	AppId	sim	Consulte o schema para restrições e campos internos
items	array	sim	Consulte o schema para restrições e campos internos

{
  "appId": "app_loja",
  "items": [
    {
      "clientId": "row-1",
      "action": "create",
      "input": {
        "appId": "app_loja",
        "domain": "go.example.com",
        "slug": "importado",
        "desktopUrl": "https://shop.example.com/one"
      }
    }
  ]
}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/link-batches' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","items":[{"clientId":"row-1","action":"create","input":{"appId":"app_loja","domain":"go.example.com","slug":"importado","desktopUrl":"https://shop.example.com/one"}}]}'

Resposta: 202. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso a acompanhar.	/v1/operations/b0000000-0000-4000-8000-000000000001
Retry-After	Segundos até a próxima consulta.	1

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "kind": "batch",
    "state": "queued",
    "operationId": "b0000000-0000-4000-8000-000000000001",
    "revision": "20000000-0000-4000-8000-000000000001",
    "total": 1,
    "succeeded": 0,
    "failed": 0,
    "expiresAt": "2026-10-27T01:00:00Z",
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z",
    "downloadUrl": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /link-batches/{batchId}/items

Resultados por item, paginados.

Permissão: batches:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
batchId	path	sim	OpaqueId
limit	query	não	integer
cursor	query	não	Cursor

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/link-batches/b0000000-0000-4000-8000-000000000001/items' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": [
    {
      "clientId": "row-1",
      "ordinal": 1,
      "state": "pending",
      "result": null,
      "error": null
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /imports

Upload/registro de importação CSV/JSON.

Permissão: imports:create. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
appId	AppId	sim	Consulte o schema para restrições e campos internos
format	csv / json	sim	Valores: csv, json
content	string	sim	Máximo 24000 caracteres
mapping	object	não	Consulte o schema para restrições e campos internos

{
  "appId": "app_loja",
  "format": "csv",
  "content": "domain,slug,desktopUrl\ngo.example.com,importado,https://shop.example.com/one"
}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/imports' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","format":"csv","content":"domain,slug,desktopUrl\ngo.example.com,importado,https://shop.example.com/one"}'

Resposta: 201. Criado. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso criado.	/v1/imports/b0000000-0000-4000-8000-000000000001

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "kind": "import",
    "state": "uploaded",
    "operationId": null,
    "revision": "20000000-0000-4000-8000-000000000001",
    "total": 1,
    "succeeded": 0,
    "failed": 0,
    "expiresAt": "2026-10-27T01:00:00Z",
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z",
    "downloadUrl": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

POST /imports/{importId}/validate

Validar e produzir relatório sem gravar links.

Permissão: imports:validate. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
importId	path	sim	OpaqueId
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição

{}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/imports/b0000000-0000-4000-8000-000000000001/validate' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data '{}'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "kind": "import",
    "state": "validated",
    "operationId": null,
    "revision": "20000000-0000-4000-8000-000000000001",
    "total": 1,
    "succeeded": 0,
    "failed": 0,
    "expiresAt": "2026-10-27T01:00:00Z",
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z",
    "downloadUrl": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

POST /imports/{importId}/commit

Executar importação validada.

Permissão: imports:commit. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
importId	path	sim	OpaqueId
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.
If-Match	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição

{}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/imports/b0000000-0000-4000-8000-000000000001/commit' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'If-Match: "20000000-0000-4000-8000-000000000001"' \
  --header 'Content-Type: application/json' \
  --data '{}'

Resposta: 202. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso a acompanhar.	/v1/operations/b0000000-0000-4000-8000-000000000001
Retry-After	Segundos até a próxima consulta.	1

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "kind": "import",
    "state": "queued",
    "operationId": "b0000000-0000-4000-8000-000000000001",
    "revision": "20000000-0000-4000-8000-000000000001",
    "total": 1,
    "succeeded": 0,
    "failed": 0,
    "expiresAt": "2026-10-27T01:00:00Z",
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z",
    "downloadUrl": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

GET /imports/{importId}

Resumo, estado e erros.

Permissão: imports:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
importId	path	sim	OpaqueId

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/imports/b0000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "kind": "import",
    "state": "queued",
    "operationId": "b0000000-0000-4000-8000-000000000001",
    "revision": "20000000-0000-4000-8000-000000000001",
    "total": 1,
    "succeeded": 0,
    "failed": 0,
    "expiresAt": "2026-10-27T01:00:00Z",
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z",
    "downloadUrl": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /imports/{importId}/items

Resultados por linha.

Permissão: imports:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
importId	path	sim	OpaqueId
limit	query	não	integer
cursor	query	não	Cursor
format	query	não	json / csv

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/imports/b0000000-0000-4000-8000-000000000001/items' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": [
    {
      "clientId": "row-1",
      "ordinal": 1,
      "state": "pending",
      "result": null,
      "error": null
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /webhooks

Listar/cadastrar destino e assinaturas de eventos.

Permissão: webhooks:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
appId	query	sim	AppId
limit	query	não	integer
cursor	query	não	Cursor

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/webhooks?appId=app_loja' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": [
    {
      "id": "b0000000-0000-4000-8000-000000000001",
      "appId": "app_loja",
      "name": "Integração",
      "url": "https://hooks.example.com/agilink",
      "events": [
        "link.created"
      ],
      "enabled": true,
      "failures": 0,
      "revision": "20000000-0000-4000-8000-000000000001",
      "previousSecretExpiresAt": null,
      "createdAt": "2026-10-20T01:00:00Z",
      "updatedAt": "2026-10-20T01:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /webhooks

Listar/cadastrar destino e assinaturas de eventos.

Permissão: webhooks:create. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
appId	AppId	sim	Consulte o schema para restrições e campos internos
name	string	sim	Máximo 100 caracteres
url	string	sim	Máximo 2048 caracteres
events	array	sim	Consulte o schema para restrições e campos internos

{
  "appId": "app_loja",
  "name": "Integração",
  "url": "https://hooks.example.com/agilink",
  "events": [
    "link.created"
  ]
}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/webhooks' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","name":"Integração","url":"https://hooks.example.com/agilink","events":["link.created"]}'

Resposta: 201. Criado. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso criado.	/v1/webhooks/b0000000-0000-4000-8000-000000000001

{
  "data": {
    "webhook": {
      "id": "b0000000-0000-4000-8000-000000000001",
      "appId": "app_loja",
      "name": "Integração",
      "url": "https://hooks.example.com/agilink",
      "events": [
        "link.created"
      ],
      "enabled": true,
      "failures": 0,
      "revision": "20000000-0000-4000-8000-000000000001",
      "previousSecretExpiresAt": null,
      "createdAt": "2026-10-20T01:00:00Z",
      "updatedAt": "2026-10-20T01:00:00Z"
    },
    "secret": "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /webhooks/{webhookId}

Consultar/alterar/desativar destino.

Permissão: webhooks:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
webhookId	path	sim	OpaqueId

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/webhooks/b0000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "name": "Integração",
    "url": "https://hooks.example.com/agilink",
    "events": [
      "link.created"
    ],
    "enabled": true,
    "failures": 0,
    "revision": "20000000-0000-4000-8000-000000000001",
    "previousSecretExpiresAt": null,
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

PATCH /webhooks/{webhookId}

Consultar/alterar/desativar destino.

Permissão: webhooks:update. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
webhookId	path	sim	OpaqueId
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.
If-Match	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
name	string	não	Máximo 100 caracteres
url	string	não	Máximo 2048 caracteres
events	array	não	Consulte o schema para restrições e campos internos
enabled	boolean	não	Consulte o schema para restrições e campos internos

{
  "enabled": false
}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request PATCH 'https://api.staging.agilink.io/v1/webhooks/b0000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'If-Match: "20000000-0000-4000-8000-000000000001"' \
  --header 'Content-Type: application/json' \
  --data '{"enabled":false}'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "name": "Integração",
    "url": "https://hooks.example.com/agilink",
    "events": [
      "link.created"
    ],
    "enabled": true,
    "failures": 0,
    "revision": "20000000-0000-4000-8000-000000000001",
    "previousSecretExpiresAt": null,
    "createdAt": "2026-10-20T01:00:00Z",
    "updatedAt": "2026-10-20T01:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

DELETE /webhooks/{webhookId}

Consultar/alterar/desativar destino.

Permissão: webhooks:delete. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
webhookId	path	sim	OpaqueId
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.
If-Match	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request DELETE 'https://api.staging.agilink.io/v1/webhooks/b0000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'If-Match: "20000000-0000-4000-8000-000000000001"'

Resposta: 204. Removido. Corpo vazio; publicação da remoção acompanha outbox.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

Sem corpo de resposta.

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 422, 428, 429, 500, 503. Veja códigos e repetição.

POST /webhooks/{webhookId}/rotate-secret

Rotacionar assinatura com período de transição.

Permissão: webhooks:rotate_secret. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
webhookId	path	sim	OpaqueId
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.
If-Match	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
overlapSeconds	integer	não	Consulte o schema para restrições e campos internos

{
  "overlapSeconds": 3600
}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/webhooks/b0000000-0000-4000-8000-000000000001/rotate-secret' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'If-Match: "20000000-0000-4000-8000-000000000001"' \
  --header 'Content-Type: application/json' \
  --data '{"overlapSeconds":3600}'

Resposta: 201. Criado. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso criado.	/v1/webhooks/b0000000-0000-4000-8000-000000000001

{
  "data": {
    "webhook": {
      "id": "b0000000-0000-4000-8000-000000000001",
      "appId": "app_loja",
      "name": "Integração",
      "url": "https://hooks.example.com/agilink",
      "events": [
        "link.created"
      ],
      "enabled": true,
      "failures": 0,
      "revision": "20000000-0000-4000-8000-000000000001",
      "previousSecretExpiresAt": null,
      "createdAt": "2026-10-20T01:00:00Z",
      "updatedAt": "2026-10-20T01:00:00Z"
    },
    "secret": "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

POST /webhooks/{webhookId}/test

Enviar evento sintético identificado como teste.

Permissão: webhooks:test. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
webhookId	path	sim	OpaqueId
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição

{}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/webhooks/b0000000-0000-4000-8000-000000000001/test' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data '{}'

Resposta: 202. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso a acompanhar.	/v1/webhook-deliveries/b0000000-0000-4000-8000-000000000001
Retry-After	Segundos até a próxima consulta.	1

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "webhookId": "b0000000-0000-4000-8000-000000000001",
    "eventId": "b0000000-0000-4000-8000-000000000001",
    "eventType": "webhook.test",
    "test": true,
    "state": "pending",
    "attempts": 0,
    "statusCode": null,
    "errorCode": null,
    "nextAttemptAt": "2026-10-20T01:00:00Z",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-20T01:00:00Z",
    "expiresAt": "2026-10-27T01:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /webhooks/{webhookId}/deliveries

Histórico paginado.

Permissão: webhooks:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
webhookId	path	sim	OpaqueId
limit	query	não	integer
cursor	query	não	Cursor

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/webhooks/b0000000-0000-4000-8000-000000000001/deliveries' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": [
    {
      "id": "b0000000-0000-4000-8000-000000000001",
      "appId": "app_loja",
      "webhookId": "b0000000-0000-4000-8000-000000000001",
      "eventId": "b0000000-0000-4000-8000-000000000001",
      "eventType": "webhook.test",
      "test": true,
      "state": "pending",
      "attempts": 0,
      "statusCode": null,
      "errorCode": null,
      "nextAttemptAt": "2026-10-20T01:00:00Z",
      "revision": "20000000-0000-4000-8000-000000000001",
      "createdAt": "2026-10-20T01:00:00Z",
      "expiresAt": "2026-10-27T01:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /webhook-deliveries/{deliveryId}

Detalhe sanitizado.

Permissão: webhooks:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
deliveryId	path	sim	OpaqueId

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/webhook-deliveries/b0000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "webhookId": "b0000000-0000-4000-8000-000000000001",
    "eventId": "b0000000-0000-4000-8000-000000000001",
    "eventType": "webhook.test",
    "test": true,
    "state": "pending",
    "attempts": 0,
    "statusCode": null,
    "errorCode": null,
    "nextAttemptAt": "2026-10-20T01:00:00Z",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-20T01:00:00Z",
    "expiresAt": "2026-10-27T01:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /webhook-deliveries/{deliveryId}/retry

Reentrega explicitamente autorizada.

Permissão: webhooks:retry. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
deliveryId	path	sim	OpaqueId
Idempotency-Key	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido.
If-Match	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição

{}

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request POST 'https://api.staging.agilink.io/v1/webhook-deliveries/b0000000-0000-4000-8000-000000000001/retry' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'If-Match: "20000000-0000-4000-8000-000000000001"' \
  --header 'Content-Type: application/json' \
  --data '{}'

Resposta: 202. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
X-Request-Id	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
Cache-Control	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
ETag	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
Location	Recurso a acompanhar.	/v1/webhook-deliveries/b0000000-0000-4000-8000-000000000001
Retry-After	Segundos até a próxima consulta.	1

{
  "data": {
    "id": "b0000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "webhookId": "b0000000-0000-4000-8000-000000000001",
    "eventId": "b0000000-0000-4000-8000-000000000001",
    "eventType": "webhook.test",
    "test": true,
    "state": "pending",
    "attempts": 0,
    "statusCode": null,
    "errorCode": null,
    "nextAttemptAt": "2026-10-20T01:00:00Z",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-20T01:00:00Z",
    "expiresAt": "2026-10-27T01:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.