Skip to main content
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:
  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: 
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": "[email protected]"
    }
  }'
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
  }'

​
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

Use nomes descritivos para seus triggers: “Processar Pedidos” em vez de “Trigger 1”.
Configure rate limiting apropriado para webhooks para proteger contra abuso e controlar custos.
Configure retry policy adequada para garantir que execuções falhadas sejam retentadas.
Torne workflows idempotentes para permitir retries seguros e evitar processamento duplicado.
Monitore triggers ativos e execuções falhadas para garantir que workflows estão funcionando corretamente.
Use autenticação via API key ao chamar webhooks do Triglit.

​
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
Use o endpoint de listagem de triggers para ver todos os triggers ativos e suas configurações.