> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triglit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Entenda como os triggers iniciam workflows no Triglit

**Triggers** são mecanismos que iniciam a execução de workflows. Eles definem **quando** e **como** um workflow deve ser executado.

## O que é um Trigger?

Um trigger é uma configuração que:

* Está associado a uma versão de workflow
* Define condições para iniciar execuções
* Pode ser ativado ou desativado
* Suporta diferentes tipos (webhook, schedule)

## Estrutura de um Trigger

```json theme={null}
{
  "id": "trigger_123",
  "tenantId": "tenant_abc",
  "workflowVersionId": "version_456",
  "name": "Processar Pedidos",
  "type": "webhook",
  "config": {
    "webhookConfig": null,
    "rateLimit": {
      "maxRequests": 100,
      "windowMs": 60000
    },
    "retryPolicy": {
      "maxRetries": 3,
      "backoffMs": 1000,
      "maxBackoffMs": 10000
    }
  },
  "isActive": true,
  "createdAt": "2024-01-15T10:00:00Z"
}
```

## Tipos de Triggers

### Webhook Trigger

Inicia workflow quando o **cliente chama o webhook do Triglit** via requisição HTTP. Na prática, funciona como um **trigger de evento**, onde o cliente chama o webhook quando um evento acontece no sistema dele.

**Exemplo de uso:**

* Cliente tem um CRM e configura um workflow para processar novos leads
* Quando um novo lead é cadastrado no CRM do cliente, o sistema do cliente chama o webhook do Triglit
* O Triglit recebe a chamada e inicia o workflow automaticamente

```json theme={null}
{
  "type": "webhook",
  "config": {
    "webhookConfig": null,
    "rateLimit": {
      "maxRequests": 100,
      "windowMs": 60000
    },
    "retryPolicy": {
      "maxRetries": 3,
      "backoffMs": 1000,
      "maxBackoffMs": 10000
    }
  }
}
```

#### Eventos em Webhook Triggers

Você pode associar um **evento** a um webhook trigger para facilitar a busca e iniciação de workflows por nome de evento ao invés de ID do trigger.

**Exemplo com evento:**

```json theme={null}
{
  "type": "webhook",
  "config": {
    "webhookConfig": {
      "event": "lead.created"
    },
    "rateLimit": {
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}
```

**Benefícios:**

* ✅ Buscar e iniciar workflows por evento sem precisar conhecer IDs de triggers
* ✅ Organizar triggers por eventos do seu sistema (ex: `lead.created`, `order.paid`, `user.registered`)
* ✅ Iniciar múltiplos workflows do mesmo evento com uma única chamada

**Eventos Customizados:**
Se você configurou eventos customizados no seu tenant (com `name` e `label`), o campo `event` será validado e apenas valores permitidos serão aceitos. Caso contrário, você pode usar qualquer string como nome de evento.

**Características:**

* ✅ URL única por trigger (gerada automaticamente)
* ✅ Payload passado para o workflow
* ✅ Ideal para integrar eventos do sistema do cliente
* ✅ Configuração opcional de rate limiting
* ✅ Configuração opcional de retry policy

**URL do Webhook:**

```
https://api.triglit.com/v1/gateway/webhooks/{triggerId}
```

**Como funciona:**

1. Cliente cria um trigger webhook no Triglit
2. Cliente recebe a URL do webhook (ex: `https://api.triglit.com/v1/gateway/webhooks/trg_abc123`)
3. Cliente configura seu sistema para chamar essa URL quando um evento acontecer (ex: novo lead cadastrado)
4. Quando o evento ocorre, o sistema do cliente faz uma requisição HTTP para a URL do webhook
5. O Triglit recebe a requisição e inicia o workflow automaticamente

#### Iniciar Triggers por Evento

Ao invés de chamar o webhook por ID do trigger, você pode iniciar todos os triggers webhook de um evento específico usando o endpoint `/webhook/by-event`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.triglit.com/v1/gateway/triggers/webhook/by-event" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "event": "lead.created",
      "subTenantId": "sub_tenant_123",
      "eventData": {
        "leadId": "lead_456",
        "name": "João Silva",
        "email": "joao@example.com"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  import Triglit from 'triglit';

  const client = new Triglit({ apiKey: 'sk_sua_chave' });

  // Inicia todos os triggers webhook do evento "lead.created"
  const result = await client.triggers.triggerByEvent({
    event: 'lead.created',
    subTenantId: 'sub_tenant_123', // Opcional: filtra por sub-tenant
    eventData: {
      leadId: 'lead_456',
      name: 'João Silva',
      email: 'joao@example.com'
    }
  });

  // Retorna lista de triggers iniciados
  console.log(`Iniciados ${result.total} triggers:`);
  result.triggers.forEach(trigger => {
    console.log(`- Trigger ${trigger.triggerId} (dedupeKey: ${trigger.dedupeKey})`);
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-API-Key': 'sk_sua_chave',
      'Content-Type': 'application/json'
  }

  data = {
      'event': 'lead.created',
      'subTenantId': 'sub_tenant_123',  # Opcional: filtra por sub-tenant
      'eventData': {
          'leadId': 'lead_456',
          'name': 'João Silva',
          'email': 'joao@example.com'
      }
  }

  response = requests.post(
      'https://api.triglit.com/v1/gateway/triggers/webhook/by-event',
      headers=headers,
      json=data
  )

  result = response.json()
  print(f"Iniciados {result['total']} triggers")
  for trigger in result['triggers']:
      print(f"- Trigger {trigger['triggerId']} (dedupeKey: {trigger['dedupeKey']})")
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "triggers": [
    {
      "triggerId": "trg_abc123",
      "dedupeKey": "tenant_123:sub_tenant_123:trg_abc123:1705312200000"
    },
    {
      "triggerId": "trg_def456",
      "dedupeKey": "tenant_123:sub_tenant_123:trg_def456:1705312200000"
    }
  ],
  "total": 2
}
```

**Parâmetros:**

* `event` (obrigatório): Nome do evento (ex: `"lead.created"`)
* `subTenantId` (opcional): ID do sub-tenant para filtrar triggers. Se fornecido, apenas triggers desse sub-tenant serão iniciados
* `eventData` (opcional): Dados do evento que serão passados para os workflows

**Vantagens:**

* ✅ Não precisa conhecer IDs de triggers
* ✅ Inicia múltiplos workflows do mesmo evento com uma única chamada
* ✅ Filtra automaticamente por sub-tenant quando necessário
* ✅ Apenas triggers webhook **ativos** com o evento correspondente são iniciados

### Schedule Trigger

Inicia workflow em intervalos regulares usando cron.

```json theme={null}
{
  "type": "schedule",
  "config": {
    "scheduleConfig": {
      "cron": "0 0 * * *",
      "timezone": "America/Sao_Paulo"
    },
    "retryPolicy": {
      "maxRetries": 3,
      "backoffMs": 1000,
      "maxBackoffMs": 10000
    }
  }
}
```

**Alternativa com intervalo:**

```json theme={null}
{
  "type": "schedule",
  "config": {
    "scheduleConfig": {
      "intervalMs": 3600000,
      "timezone": "America/Sao_Paulo"
    }
  }
}
```

**Exemplos de Cron:**

* `0 0 * * *`: Diariamente à meia-noite
* `0 */6 * * *`: A cada 6 horas
* `0 9 * * 1-5`: Segunda a sexta às 9h
* `*/15 * * * *`: A cada 15 minutos

**Intervalo em milissegundos:**

* `60000`: A cada 1 minuto
* `3600000`: A cada 1 hora
* `86400000`: A cada 24 horas

**Características:**

* ✅ Expressões cron padrão ou intervalos em milissegundos
* ✅ Suporte a timezones
* ✅ Execução garantida (com retry)
* ✅ Mínimo de 1 minuto (60000ms) para intervalos

## Criando um Trigger

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.triglit.com/v1/gateway/triggers" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "workflowVersionId": "version_456",
      "name": "Processar Pedidos",
      "type": "webhook",
      "config": {
        "webhookConfig": null
      },
      "isActive": true
    }'
  ```

  ```javascript JavaScript theme={null}
  import Triglit from 'triglit';

  const client = new Triglit({ apiKey: 'sk_sua_chave' });
  const trigger = await client.triggers.create({
    workflowVersionId: 'version_456',
    name: 'Processar Pedidos',
    type: 'webhook',
    config: {
      webhookConfig: null,
      rateLimit: {
        maxRequests: 100,
        windowMs: 60000
      }
    },
    isActive: true
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-API-Key': 'sk_sua_chave',
      'Content-Type': 'application/json'
  }

  data = {
      'workflowVersionId': 'version_456',
      'name': 'Processar Pedidos',
      'type': 'webhook',
      'config': {
          'webhookConfig': None,
          'rateLimit': {
              'maxRequests': 100,
              'windowMs': 60000
          }
      },
      'isActive': True
  }

  response = requests.post(
      'https://api.triglit.com/v1/gateway/triggers',
      headers=headers,
      json=data
  )

  trigger = response.json()
  ```
</CodeGroup>

## Ativando e Desativando

Você pode ativar/desativar triggers sem deletá-los:

```bash theme={null}
# Desativar
PATCH /v1/gateway/triggers/{id}
{
  "isActive": false
}

# Reativar
PATCH /v1/gateway/triggers/{id}
{
  "isActive": true
}
```

## Payload e Contexto

Quando um trigger é ativado, os dados são passados para o workflow:

### Webhook

Quando o cliente chama o webhook, os dados da requisição HTTP são passados para o workflow:

```json theme={null}
{
  "headers": { "X-Custom": "value" },
  "query": { "param": "value" },
  "body": { "orderId": "123" }
}
```

### Schedule

Quando um schedule trigger é executado, os dados de contexto são passados:

```json theme={null}
{
  "triggeredAt": "2024-01-15T10:00:00Z",
  "cron": "0 0 * * *",
  "timezone": "America/Sao_Paulo"
}
```

## Múltiplos Triggers

Um workflow pode ter **múltiplos triggers**:

```json theme={null}
{
  "workflowVersionId": "version_456",
  "triggers": [
    {
      "type": "webhook",
      "config": { "webhookConfig": null }
    },
    {
      "type": "schedule",
      "config": {
        "scheduleConfig": {
          "cron": "0 0 * * *",
          "timezone": "America/Sao_Paulo"
        }
      }
    }
  ]
}
```

## Configurações Opcionais

### Rate Limiting

Limite o número de requisições por período:

```json theme={null}
{
  "type": "webhook",
  "config": {
    "webhookConfig": null,
    "rateLimit": {
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}
```

### Retry Policy

Configure política de retry para execuções:

```json theme={null}
{
  "type": "webhook",
  "config": {
    "webhookConfig": null,
    "retryPolicy": {
      "maxRetries": 3,
      "backoffMs": 1000,
      "maxBackoffMs": 10000
    }
  }
}
```

### Timeout

Configure timeout para execuções:

```json theme={null}
{
  "type": "webhook",
  "config": {
    "webhookConfig": null,
    "timeoutMs": 30000
  }
}
```

## Limites Padrão

Triggers têm limites padrão para proteger contra abuso:

* **Webhook**: 100 requisições/minuto por trigger (configurável via `rateLimit`)
* **Schedule**: Sem limite (execução controlada pelo cron/intervalo)

## Boas Práticas

<AccordionGroup>
  <Accordion title="Nomes Descritivos">
    Use nomes descritivos para seus triggers: "Processar Pedidos" em vez de "Trigger 1".
  </Accordion>

  <Accordion title="Rate Limiting">
    Configure rate limiting apropriado para webhooks para proteger contra abuso e controlar custos.
  </Accordion>

  <Accordion title="Retry Policy">
    Configure retry policy adequada para garantir que execuções falhadas sejam retentadas.
  </Accordion>

  <Accordion title="Idempotência">
    Torne workflows idempotentes para permitir retries seguros e evitar processamento duplicado.
  </Accordion>

  <Accordion title="Monitoramento">
    Monitore triggers ativos e execuções falhadas para garantir que workflows estão funcionando corretamente.
  </Accordion>

  <Accordion title="Segurança">
    Use autenticação via API key ao chamar webhooks do Triglit.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Trigger não está executando

1. Verifique se `isActive: true`
2. Confirme que a versão do workflow está publicada
3. Verifique logs de erro
4. Valide configuração do trigger

### Webhook retorna 404

1. Confirme que o trigger existe e está ativo
2. Verifique se está usando o ID correto do trigger na URL
3. Confirme que a URL está no formato: `https://api.triglit.com/v1/gateway/webhooks/{triggerId}`

### Schedule não executa

1. Valide expressão cron
2. Verifique timezone
3. Confirme que trigger está ativo

<Tip>
  Use o endpoint de listagem de triggers para ver todos os triggers ativos e suas configurações.
</Tip>