---
title: Endpoints de automação, lotes e webhooks
description: Referência A4b com parâmetros e exemplos de request e response.
---

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](/api/automacao-lotes-webhooks/) e a [migração de tokens](/api/migracao-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 |

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

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

```sh
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 |

```json
{
  "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](/api/errors/).

## 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):

```sh
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" |

```json
{
  "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](/api/errors/).

## 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):

```sh
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](/api/errors/).

## 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 |

```json
{
  "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):

```sh
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 |

```json
{
  "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](/api/errors/).

## 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):

```sh
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 |

```json
{
  "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](/api/errors/).

## 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 |

```json
{
  "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):

```sh
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 |

```json
{
  "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](/api/errors/).

## 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 |
| --- | --- | --- | --- |


```json
{}
```

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

```sh
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" |

```json
{
  "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](/api/errors/).

## 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 |
| --- | --- | --- | --- |


```json
{}
```

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

```sh
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 |

```json
{
  "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](/api/errors/).

## 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):

```sh
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" |

```json
{
  "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](/api/errors/).

## 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):

```sh
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 |

```json
{
  "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](/api/errors/).

## 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):

```sh
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 |

```json
{
  "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](/api/errors/).

## 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 |

```json
{
  "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):

```sh
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 |

```json
{
  "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](/api/errors/).

## 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):

```sh
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" |

```json
{
  "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](/api/errors/).

## 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 |

```json
{
  "enabled": false
}
```

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

```sh
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" |

```json
{
  "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](/api/errors/).

## 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):

```sh
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](/api/errors/).

## 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 |

```json
{
  "overlapSeconds": 3600
}
```

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

```sh
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 |

```json
{
  "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](/api/errors/).

## 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 |
| --- | --- | --- | --- |


```json
{}
```

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

```sh
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 |

```json
{
  "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](/api/errors/).

## 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):

```sh
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 |

```json
{
  "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](/api/errors/).

## 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):

```sh
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" |

```json
{
  "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](/api/errors/).

## 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 |
| --- | --- | --- | --- |


```json
{}
```

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

```sh
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 |

```json
{
  "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](/api/errors/).