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

{
  "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

{
  "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:

{
  "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:

Cliente cria um trigger webhook no Triglit
Cliente recebe a URL do webhook (ex: https://api.triglit.com/v1/gateway/webhooks/trg_abc123)
Cliente configura seu sistema para chamar essa URL quando um evento acontecer (ex: novo lead cadastrado)
Quando o evento ocorre, o sistema do cliente faz uma requisição HTTP para a URL do webhook
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:

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"
    }
  }'

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})`);
});

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']})")

Resposta:

{
  "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.

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

Alternativa com intervalo:

{
  "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

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
  }'

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
});

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()

Ativando e Desativando

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

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

{
  "headers": { "X-Custom": "value" },
  "query": { "param": "value" },
  "body": { "orderId": "123" }
}

Schedule

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

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

Múltiplos Triggers

Um workflow pode ter múltiplos triggers:

{
  "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:

{
  "type": "webhook",
  "config": {
    "webhookConfig": null,
    "rateLimit": {
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}

Retry Policy

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

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

Timeout

Configure timeout para execuções:

{
  "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

Nomes Descritivos

Use nomes descritivos para seus triggers: “Processar Pedidos” em vez de “Trigger 1”.

Rate Limiting

Configure rate limiting apropriado para webhooks para proteger contra abuso e controlar custos.

Retry Policy

Configure retry policy adequada para garantir que execuções falhadas sejam retentadas.

Idempotência

Torne workflows idempotentes para permitir retries seguros e evitar processamento duplicado.

Monitoramento

Monitore triggers ativos e execuções falhadas para garantir que workflows estão funcionando corretamente.

Segurança

Use autenticação via API key ao chamar webhooks do Triglit.

Troubleshooting

Trigger não está executando

Verifique se isActive: true
Confirme que a versão do workflow está publicada
Verifique logs de erro
Valide configuração do trigger

Webhook retorna 404

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

Schedule não executa

Valide expressão cron
Verifique timezone
Confirme que trigger está ativo

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

​O que é um Trigger?

​Estrutura de um Trigger

​Tipos de Triggers

​Webhook Trigger

​Eventos em Webhook Triggers

​Iniciar Triggers por Evento

​Schedule Trigger

​Criando um Trigger

​Ativando e Desativando

​Payload e Contexto

​Webhook

​Schedule

​Múltiplos Triggers

​Configurações Opcionais

​Rate Limiting

​Retry Policy

​Timeout

​Limites Padrão

​Boas Práticas

​Troubleshooting

​Trigger não está executando

​Webhook retorna 404

​Schedule não executa

O que é um Trigger?

Estrutura de um Trigger

Tipos de Triggers

Webhook Trigger

Eventos em Webhook Triggers

Iniciar Triggers por Evento

Schedule Trigger

Criando um Trigger

Ativando e Desativando

Payload e Contexto

Webhook

Schedule

Múltiplos Triggers

Configurações Opcionais

Rate Limiting

Retry Policy

Timeout

Limites Padrão

Boas Práticas

Troubleshooting

Trigger não está executando

Webhook retorna 404

Schedule não executa