Subscriptions

Gerenciamento de webhook subscriptions para receber notificações de eventos.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/subscriptions`	Criar subscription	`WEBHOOKS_SUBSCRIPTIONS_CREATE`
GET	`/api/v1/subscriptions`	Listar subscriptions	`WEBHOOKS_SUBSCRIPTIONS_READ`
GET	`/api/v1/subscriptions/:id`	Obter subscription por ID	`WEBHOOKS_SUBSCRIPTIONS_READ`
PATCH	`/api/v1/subscriptions/:id`	Atualizar subscription	`WEBHOOKS_SUBSCRIPTIONS_UPDATE`
DELETE	`/api/v1/subscriptions/:id`	Excluir subscription	`WEBHOOKS_SUBSCRIPTIONS_DELETE`
POST	`/api/v1/subscriptions/:id/pause`	Pausar subscription	`WEBHOOKS_SUBSCRIPTIONS_UPDATE`
POST	`/api/v1/subscriptions/:id/resume`	Retomar subscription	`WEBHOOKS_SUBSCRIPTIONS_UPDATE`
POST	`/api/v1/subscriptions/:id/test`	Testar endpoint	`WEBHOOKS_SUBSCRIPTIONS_READ`

Atributos

Campo	Tipo	Descrição
`name`	string	Nome identificador da subscription
`endpointUrl`	string	URL do endpoint para receber eventos
`eventFilters`	array	Lista de tipos de eventos a receber
`status`	enum	Status: `ACTIVE`, `PAUSED`, `DISABLED`
`timeoutMs`	number	Timeout da requisição em ms (padrão: 30000)
`retryConfig`	object	Configuração de retry
`customHeaders`	object	Headers customizados a enviar
`description`	string	Descrição da subscription
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização
`createdBy`	string	ID do usuário que criou
`updatedBy`	string	ID do usuário que atualizou

Configuração de Retry (retryConfig)

Campo	Tipo	Padrão	Descrição
`maxRetries`	number	5	Número máximo de tentativas
`retryBackoffMs`	number	1000	Tempo inicial de espera (ms)
`retryBackoffMultiplier`	number	2.0	Multiplicador do backoff

Status da Subscription

Status	Descrição
`ACTIVE`	Subscription ativa, recebendo eventos
`PAUSED`	Pausada temporariamente pelo usuário
`DISABLED`	Desabilitada automaticamente (muitas falhas)

Criar Subscription

POST /api/v1/subscriptions

Cria uma nova webhook subscription.

Atributos

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da subscription
`endpointUrl`	string	Sim	URL do endpoint (HTTPS)
`eventFilters`	array	Sim	Tipos de eventos
`timeoutMs`	number	Não	Timeout (padrão: 30000)
`retryConfig`	object	Não	Configuração de retry
`customHeaders`	object	Não	Headers customizados
`description`	string	Não	Descrição

cURL
JavaScript

curl -X POST 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Notificações de Billing",
    "endpointUrl": "https://minha-app.com/webhooks/billing",
    "eventFilters": [
      "billing.invoice.created",
      "billing.invoice.paid",
      "billing.payment.completed"
    ],
    "timeoutMs": 30000,
    "retryConfig": {
      "maxRetries": 5,
      "retryBackoffMs": 1000,
      "retryBackoffMultiplier": 2.0
    },
    "customHeaders": {
      "X-App-Secret": "meu-segredo"
    },
    "description": "Webhook para eventos de faturamento"
  }'

const response = await fetch('https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Notificações de Billing',
    endpointUrl: 'https://minha-app.com/webhooks/billing',
    eventFilters: [
      'billing.invoice.created',
      'billing.invoice.paid',
      'billing.payment.completed',
    ],
    timeoutMs: 30000,
    retryConfig: {
      maxRetries: 5,
      retryBackoffMs: 1000,
      retryBackoffMultiplier: 2.0,
    },
    customHeaders: {
      'X-App-Secret': 'meu-segredo',
    },
    description: 'Webhook para eventos de faturamento',
  }),
});

const { data } = await response.json();
console.log(`Subscription criada: ${data.id}`);

Response (201 Created)

{
  "data": {
    "type": "webhook-subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "links": {
      "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070"
    },
    "attributes": {
      "name": "Notificações de Billing",
      "endpointUrl": "https://minha-app.com/webhooks/billing",
      "eventFilters": [
        "billing.invoice.created",
        "billing.invoice.paid",
        "billing.payment.completed"
      ],
      "status": "ACTIVE",
      "timeoutMs": 30000,
      "retryConfig": {
        "maxRetries": 5,
        "retryBackoffMs": 1000,
        "retryBackoffMultiplier": 2.0
      },
      "customHeaders": {
        "X-App-Secret": "meu-segredo"
      },
      "description": "Webhook para eventos de faturamento",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "createdBy": "550e8400-e29b-41d4-a716-446655440001"
    }
  },
  "links": {
    "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070"
  }
}

Listar Subscriptions

GET /api/v1/subscriptions

Lista todas as webhook subscriptions com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[status]`	enum	Filtrar por status

cURL
JavaScript

curl 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions?filter[status]=ACTIVE' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[status]': 'ACTIVE',
});

const response = await fetch(`https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de subscriptions: ${meta.totalItems}`);

Response (200 OK)

{
  "data": [
    {
      "type": "webhook-subscriptions",
      "id": "550e8400-e29b-41d4-a716-446655440070",
      "links": {
        "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070"
      },
      "attributes": {
        "name": "Notificações de Billing",
        "endpointUrl": "https://minha-app.com/webhooks/billing",
        "eventFilters": ["billing.invoice.created", "billing.invoice.paid"],
        "status": "ACTIVE",
        "timeoutMs": 30000,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "currentPage": 1,
    "itemsPerPage": 20
  },
  "links": {
    "self": "/api/v1/subscriptions?page[number]=1&page[size]=20"
  }
}

Obter Subscription por ID

GET /api/v1/subscriptions/:id

Obtém os detalhes de uma subscription específica.

cURL
JavaScript

curl 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440070';

const response = await fetch(`https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/${subscriptionId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Nome: ${data.attributes.name}`);
console.log(`Status: ${data.attributes.status}`);
console.log(`Eventos: ${data.attributes.eventFilters.join(', ')}`);

Response (200 OK)

{
  "data": {
    "type": "webhook-subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "links": {
      "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070"
    },
    "attributes": {
      "name": "Notificações de Billing",
      "endpointUrl": "https://minha-app.com/webhooks/billing",
      "eventFilters": [
        "billing.invoice.created",
        "billing.invoice.paid",
        "billing.payment.completed"
      ],
      "status": "ACTIVE",
      "timeoutMs": 30000,
      "retryConfig": {
        "maxRetries": 5,
        "retryBackoffMs": 1000,
        "retryBackoffMultiplier": 2.0
      },
      "customHeaders": {
        "X-App-Secret": "meu-segredo"
      },
      "description": "Webhook para eventos de faturamento",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "createdBy": "550e8400-e29b-41d4-a716-446655440001"
    }
  },
  "links": {
    "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070"
  }
}

Atualizar Subscription

PATCH /api/v1/subscriptions/:id

Atualiza os dados de uma subscription.

Atributos Atualizáveis

Campo	Tipo	Descrição
`name`	string	Nome da subscription
`endpointUrl`	string	URL do endpoint
`eventFilters`	array	Tipos de eventos
`timeoutMs`	number	Timeout em ms
`retryConfig`	object	Configuração de retry
`customHeaders`	object	Headers customizados
`description`	string	Descrição

cURL
JavaScript

curl -X PATCH 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventFilters": [
      "billing.invoice.created",
      "billing.invoice.paid",
      "billing.invoice.overdue",
      "billing.payment.completed",
      "billing.payment.failed"
    ],
    "retryConfig": {
      "maxRetries": 10
    }
  }'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440070';

const response = await fetch(`https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/${subscriptionId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    eventFilters: [
      'billing.invoice.created',
      'billing.invoice.paid',
      'billing.invoice.overdue',
      'billing.payment.completed',
      'billing.payment.failed',
    ],
    retryConfig: {
      maxRetries: 10,
    },
  }),
});

const { data } = await response.json();
console.log(`Eventos atualizados: ${data.attributes.eventFilters.length}`);

Response (200 OK)

{
  "data": {
    "type": "webhook-subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "attributes": {
      "name": "Notificações de Billing",
      "endpointUrl": "https://minha-app.com/webhooks/billing",
      "eventFilters": [
        "billing.invoice.created",
        "billing.invoice.paid",
        "billing.invoice.overdue",
        "billing.payment.completed",
        "billing.payment.failed"
      ],
      "status": "ACTIVE",
      "timeoutMs": 30000,
      "retryConfig": {
        "maxRetries": 10,
        "retryBackoffMs": 1000,
        "retryBackoffMultiplier": 2.0
      },
      "updatedAt": "2024-01-15T11:00:00Z",
      "updatedBy": "550e8400-e29b-41d4-a716-446655440001"
    }
  }
}

Excluir Subscription

DELETE /api/v1/subscriptions/:id

Remove uma webhook subscription.

cURL
JavaScript

curl -X DELETE 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440070';

const response = await fetch(`https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/${subscriptionId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

if (response.status === 204) {
  console.log('Subscription excluída com sucesso');
}

Response (204 No Content)

Sem corpo de resposta.

Pausar Subscription

POST /api/v1/subscriptions/:id/pause

Pausa uma subscription temporariamente. Eventos não serão entregues enquanto pausada.

cURL
JavaScript

curl -X POST 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070/pause' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440070';

const response = await fetch(`https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/${subscriptionId}/pause`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`); // PAUSED

Response (200 OK)

{
  "data": {
    "type": "webhook-subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "attributes": {
      "name": "Notificações de Billing",
      "status": "PAUSED",
      "updatedAt": "2024-01-15T12:00:00Z"
    }
  }
}

Retomar Subscription

POST /api/v1/subscriptions/:id/resume

Retoma uma subscription que estava pausada.

cURL
JavaScript

curl -X POST 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070/resume' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440070';

const response = await fetch(`https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/${subscriptionId}/resume`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`); // ACTIVE

Response (200 OK)

{
  "data": {
    "type": "webhook-subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "attributes": {
      "name": "Notificações de Billing",
      "status": "ACTIVE",
      "updatedAt": "2024-01-15T13:00:00Z"
    }
  }
}

Testar Subscription

POST /api/v1/subscriptions/:id/test

Envia um evento de teste para verificar se o endpoint está funcionando.

cURL
JavaScript

curl -X POST 'https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440070/test' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440070';

const response = await fetch(`https://webhooks-engine.stg.catalisa.app/api/v1/subscriptions/${subscriptionId}/test`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
if (data.attributes.success) {
  console.log(`Teste bem-sucedido!`);
  console.log(`Status Code: ${data.attributes.responseStatusCode}`);
  console.log(`Tempo de resposta: ${data.attributes.responseTimeMs}ms`);
} else {
  console.log(`Teste falhou: ${data.attributes.errorMessage}`);
}

Response (200 OK) - Sucesso

{
  "data": {
    "type": "webhook-test-result",
    "attributes": {
      "success": true,
      "responseStatusCode": 200,
      "responseTimeMs": 145
    }
  }
}

Response (200 OK) - Falha

{
  "data": {
    "type": "webhook-test-result",
    "attributes": {
      "success": false,
      "responseStatusCode": 500,
      "responseTimeMs": 2500,
      "errorMessage": "Internal Server Error"
    }
  }
}

Filtros de Eventos

Usando Wildcards

Você pode usar wildcards para assinar múltiplos eventos:

{
  "eventFilters": [
    "billing.*",           // Todos os eventos de billing
    "billing.invoice.*",   // Todos os eventos de invoice
    "*"                    // Todos os eventos (use com cuidado)
  ]
}

Exemplos de Configuração

Notificações Financeiras

{
  "eventFilters": [
    "billing.invoice.created",
    "billing.invoice.paid",
    "billing.invoice.overdue",
    "billing.payment.completed",
    "billing.payment.failed"
  ]
}

Alterações de Usuários

{
  "eventFilters": [
    "iam.user.created",
    "iam.user.updated",
    "iam.user.deleted"
  ]
}

Eventos de Produtos

{
  "eventFilters": [
    "products.product.created",
    "products.product.updated",
    "customers.person.created"
  ]
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (URL, eventFilters, etc.)
400	`VALIDATION`	URL deve usar HTTPS
404	`NOT_FOUND`	Subscription não encontrada
409	`CONFLICT`	Subscription não está ativa (para pausar)
409	`CONFLICT`	Subscription não está pausada (para retomar)
409	`CONFLICT`	Limite de subscriptions atingido

Endpoints​

Atributos​

Configuração de Retry (retryConfig)​

Status da Subscription​

Criar Subscription​

Atributos​

Response (201 Created)​

Listar Subscriptions​

Query Parameters​

Response (200 OK)​

Obter Subscription por ID​

Response (200 OK)​

Atualizar Subscription​

Atributos Atualizáveis​

Response (200 OK)​

Excluir Subscription​

Response (204 No Content)​

Pausar Subscription​

Response (200 OK)​

Retomar Subscription​

Response (200 OK)​

Testar Subscription​

Response (200 OK) - Sucesso​

Response (200 OK) - Falha​

Filtros de Eventos​

Usando Wildcards​

Exemplos de Configuração​

Notificações Financeiras​

Alterações de Usuários​

Eventos de Produtos​

Erros Comuns​

Endpoints

Atributos

Configuração de Retry (retryConfig)

Status da Subscription

Criar Subscription

Atributos

Response (201 Created)

Listar Subscriptions

Query Parameters

Response (200 OK)

Obter Subscription por ID

Response (200 OK)

Atualizar Subscription

Atributos Atualizáveis

Response (200 OK)

Excluir Subscription

Response (204 No Content)

Pausar Subscription

Response (200 OK)

Retomar Subscription

Response (200 OK)

Testar Subscription

Response (200 OK) - Sucesso

Response (200 OK) - Falha

Filtros de Eventos

Usando Wildcards

Exemplos de Configuração

Notificações Financeiras

Alterações de Usuários

Eventos de Produtos

Erros Comuns