---
title: "Referência de Tipos de Eventos"
description: "Guia de referência completo para todos os tipos de eventos webhook do Brevo com exemplos de integração para a plataforma de fidelidade Tajo"
url: https://tajo.io/pt/docs/webhooks-events/event-types/
markdown: https://tajo.io/pt/docs/webhooks-events/event-types.md
lang: pt-BR
robots: noindex
---

Solicite acesso antecipado

Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo.

# Referência de Tipos de Eventos

Este guia de referência completo abrange todos os tipos de eventos webhook disponíveis no Brevo, com exemplos específicos para integração na plataforma de fidelidade Tajo.

## Eventos de Email

### delivered

Acionado quando um email é entregue com sucesso na caixa de correio do destinatário.

**Exemplo de Payload:**

```json
{
  "event": "delivered",
  "email": "customer@example.com",
  "id": 123456,
  "date": "2024-01-25 14:30:00",
  "ts": 1640995200,
  "message-id": "<202401251430.123456@mail.brevo.com>",
  "template_id": 101,
  "tags": ["loyalty", "points-earned"],
  "sending_ip": "185.107.232.1",
  "event_id": "evt_abc123"
}
```

**Casos de Uso na Integração Tajo:**

- Atualizar a taxa de entrega bem-sucedida nos perfis de clientes
- Acionar ações de acompanhamento para campanhas de fidelidade
- Monitorizar o desempenho de entrega de emails por nível

```javascript
async function handleEmailDelivered(event) {
  const customer = await loyaltyService.getCustomer(event.email);

  // Update delivery stats
  await loyaltyService.updateEngagement(event.email, {
    emailsDelivered: customer.emailsDelivered + 1,
    lastEmailDelivered: new Date(event.date),
    deliveryRate: calculateDeliveryRate(customer)
  });

  // Track loyalty campaign delivery
  if (event.tags.includes('loyalty')) {
    await loyaltyService.trackCampaignMetric('loyalty_email_delivered', {
      email: event.email,
      template_id: event.template_id,
      tier: customer.loyaltyTier
    });
  }
}
```

### opened

Acionado quando um destinatário abre um email (rastreia o carregamento do pixel).

**Exemplo de Payload:**

```json
{
  "event": "opened",
  "email": "customer@example.com",
  "date": "2024-01-25 15:45:00",
  "ts": 1641000300,
  "message-id": "<202401251430.123456@mail.brevo.com>",
  "template_id": 101,
  "tags": ["loyalty", "tier-upgrade"],
  "user-agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
  "geo": {
    "country": "US",
    "region": "CA",
    "city": "San Francisco"
  }
}
```

**Casos de Uso na Integração Tajo:**

- Aumentar a pontuação de envolvimento do cliente
- Monitorizar a eficácia das campanhas de fidelidade
- Acionar recompensas baseadas em comportamento
- Personalizar comunicações futuras

```javascript
async function handleEmailOpened(event) {
  const customer = await loyaltyService.getCustomer(event.email);

  // Significant engagement - boost score
  await loyaltyService.updateEngagement(event.email, {
    emailsOpened: customer.emailsOpened + 1,
    lastEmailOpened: new Date(event.date),
    engagementScore: customer.engagementScore + 5,
    preferredDevice: getDeviceType(event['user-agent'])
  });

  // Reward engagement for loyalty members
  if (event.tags.includes('loyalty') && customer.loyaltyTier) {
    await loyaltyService.awardEngagementBonus(event.email, {
      type: 'email_engagement',
      points: getEngagementPoints(customer.loyaltyTier),
      reason: 'Email opened'
    });
  }

  // Track timing patterns for optimization
  await loyaltyService.recordEngagementTime(event.email, {
    campaign: event.template_id,
    openTime: new Date(event.date),
    timezone: getTimezone(event.geo)
  });
}
```

### clicked

Acionado quando um destinatário clica num link de um email.

**Exemplo de Payload:**

```json
{
  "event": "clicked",
  "email": "customer@example.com",
  "date": "2024-01-25 16:20:00",
  "ts": 1641002400,
  "message-id": "<202401251430.123456@mail.brevo.com>",
  "template_id": 101,
  "tags": ["loyalty", "rewards-reminder"],
  "link": "https://yourdomain.com/rewards?utm_source=brevo&utm_campaign=loyalty",
  "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}
```

**Casos de Uso na Integração Tajo:**

- Monitorizar o desempenho do funil de conversão
- Atribuir bónus por cliques
- Identificar conteúdo de alto valor
- Otimizar o fluxo de email para o site

```javascript
async function handleEmailClicked(event) {
  const customer = await loyaltyService.getCustomer(event.email);
  const clickedUrl = new URL(event.link);

  // High-value engagement
  await loyaltyService.updateEngagement(event.email, {
    emailsClicked: customer.emailsClicked + 1,
    lastEmailClicked: new Date(event.date),
    engagementScore: customer.engagementScore + 15,
    clickThroughRate: calculateCTR(customer)
  });

  // Track specific link types
  if (clickedUrl.pathname.includes('/rewards')) {
    await loyaltyService.trackEvent(event.email, 'Rewards Page Clicked', {
      source: 'email',
      campaign: event.template_id,
      utm_campaign: clickedUrl.searchParams.get('utm_campaign')
    });

    // Award exploration bonus
    await loyaltyService.awardEngagementBonus(event.email, {
      type: 'rewards_exploration',
      points: 10,
      reason: 'Clicked rewards link'
    });
  }

  // Track product interest
  if (clickedUrl.pathname.includes('/products')) {
    const productId = extractProductId(clickedUrl);
    await loyaltyService.trackProductInterest(event.email, productId, {
      source: 'email_click',
      timestamp: new Date(event.date)
    });
  }
}
```

### bounced / hard\_bounced

Acionado quando um email sofre um bounce temporário (falha temporária) ou hard bounce (falha permanente).

**Exemplo de Payload:**

```json
{
  "event": "hard_bounced",
  "email": "invalid@example.com",
  "date": "2024-01-25 14:35:00",
  "ts": 1640995500,
  "message-id": "<202401251430.123456@mail.brevo.com>",
  "template_id": 101,
  "tags": ["loyalty"],
  "reason": "550 5.1.1 User unknown",
  "bounce_type": "hard"
}
```

**Casos de Uso na Integração Tajo:**

- Atualizar o estado de validade do email
- Mudar para canais de comunicação alternativos
- Limpar a base de dados de clientes
- Evitar envios futuros para endereços inválidos

```javascript
async function handleEmailBounced(event) {
  const isHardBounce = event.event === 'hard_bounced' || event.bounce_type === 'hard';

  if (isHardBounce) {
    // Permanent failure - mark email as invalid
    await loyaltyService.updateCustomerStatus(event.email, {
      emailStatus: 'invalid',
      emailBounced: true,
      bounceReason: event.reason,
      lastBounce: new Date(event.date),
      communicationPreference: 'sms' // Switch to SMS if available
    });

    // Remove from email marketing lists
    await loyaltyService.removeFromEmailMarketing(event.email);

    // Suggest phone verification
    const customer = await loyaltyService.getCustomer(event.email);
    if (customer?.phone) {
      await loyaltyService.suggestPhoneVerification(customer.phone);
    }

  } else {
    // Soft bounce - temporary issue
    await loyaltyService.updateEngagement(event.email, {
      softBounceCount: customer.softBounceCount + 1,
      lastSoftBounce: new Date(event.date)
    });

    // Retry logic for soft bounces
    if (customer.softBounceCount < 5) {
      await loyaltyService.scheduleEmailRetry(event.email, event.template_id);
    }
  }
}
```

### spam

Acionado quando um destinatário marca um email como spam.

**Exemplo de Payload:**

```json
{
  "event": "spam",
  "email": "customer@example.com",
  "date": "2024-01-25 17:10:00",
  "ts": 1641005400,
  "message-id": "<202401251430.123456@mail.brevo.com>",
  "template_id": 101,
  "tags": ["loyalty", "promotional"]
}
```

**Casos de Uso na Integração Tajo:**

- Interromper imediatamente as comunicações por email
- Rever e melhorar o conteúdo dos emails
- Analisar padrões de spam por segmento
- Implementar processos de opt-in mais rigorosos

```javascript
async function handleEmailSpam(event) {
  // Immediately disable email marketing
  await loyaltyService.updateCustomerPreferences(event.email, {
    emailMarketing: false,
    marketingEnabled: false,
    spamReported: true,
    spamReportDate: new Date(event.date)
  });

  // Alert marketing team for review
  await loyaltyService.alertMarketing('spam_complaint', {
    email: event.email,
    template: event.template_id,
    campaign_tags: event.tags,
    severity: 'high'
  });

  // Analyze spam patterns
  await loyaltyService.analyzeSpamPattern({
    template_id: event.template_id,
    tags: event.tags,
    customer_segment: await loyaltyService.getCustomerSegment(event.email)
  });

  // Consider account review if multiple spam reports
  const customer = await loyaltyService.getCustomer(event.email);
  if (customer.spamReports > 2) {
    await loyaltyService.flagForReview(event.email, 'multiple_spam_reports');
  }
}
```

## Eventos de SMS

### sms\_delivered

Acionado quando um SMS é entregue com sucesso no telemóvel do destinatário.

**Exemplo de Payload:**

```json
{
  "event": "sms_delivered",
  "phone": "+1234567890",
  "date": "2024-01-25 14:45:00",
  "ts": 1640996700,
  "message-id": "sms_abc123",
  "tags": ["loyalty", "points-alert"],
  "sender": "TAJO",
  "content": "🎉 Great news! You earned 150 points from your recent purchase. Total: 1,250 points."
}
```

**Casos de Uso na Integração Tajo:**

- Confirmar a entrega bem-sucedida do SMS
- Monitorizar as taxas de envolvimento por SMS
- Validar a precisão dos números de telemóvel
- Monitorizar o desempenho de entrega por operadora

```javascript
async function handleSMSDelivered(event) {
  const customer = await loyaltyService.getCustomerByPhone(event.phone);

  await loyaltyService.updateEngagement(customer.email, {
    smsDelivered: customer.smsDelivered + 1,
    lastSMSDelivered: new Date(event.date),
    smsDeliveryRate: calculateSMSDeliveryRate(customer),
    phoneStatus: 'valid'
  });

  // Track loyalty SMS performance
  if (event.tags.includes('loyalty')) {
    await loyaltyService.trackCampaignMetric('loyalty_sms_delivered', {
      phone: event.phone,
      content_type: getSMSContentType(event.content),
      customer_tier: customer.loyaltyTier
    });
  }
}
```

### sms\_failed

Acionado quando a entrega de um SMS falha.

**Exemplo de Payload:**

```json
{
  "event": "sms_failed",
  "phone": "+1234567890",
  "date": "2024-01-25 14:32:00",
  "ts": 1640996320,
  "message-id": "sms_def456",
  "tags": ["loyalty", "urgent"],
  "sender": "TAJO",
  "reason": "Invalid phone number format",
  "error_code": "30006"
}
```

**Casos de Uso na Integração Tajo:**

- Atualizar a validade do número de telemóvel
- Mudar para notificações por email
- Limpar a base de dados de números de telemóvel
- Alertar o serviço de apoio ao cliente para verificação manual

```javascript
async function handleSMSFailed(event) {
  const customer = await loyaltyService.getCustomerByPhone(event.phone);

  await loyaltyService.updateCustomerStatus(customer.email, {
    phoneStatus: 'invalid',
    smsEnabled: false,
    smsFailureReason: event.reason,
    lastSMSFailure: new Date(event.date),
    communicationPreference: 'email'
  });

  // For urgent loyalty notifications, fall back to email
  if (event.tags.includes('urgent') || event.tags.includes('loyalty')) {
    await loyaltyService.sendEmailFallback(customer.email, {
      originalSMS: event.content,
      reason: 'SMS delivery failed'
    });
  }

  // Flag for phone number verification
  await loyaltyService.flagForPhoneVerification(customer.email);
}
```

### sms\_reply

Acionado quando um destinatário responde a um SMS.

**Exemplo de Payload:**

```json
{
  "event": "sms_reply",
  "phone": "+1234567890",
  "date": "2024-01-25 15:20:00",
  "ts": 1641000000,
  "message-id": "sms_reply_123",
  "text": "BALANCE",
  "original_message_id": "sms_abc123"
}
```

**Casos de Uso na Integração Tajo:**

- Processar comandos do programa de fidelidade
- Gerir pedidos de apoio ao cliente
- Atualizar preferências de comunicação
- Acionar respostas automáticas

```javascript
async function handleSMSReply(event) {
  const customer = await loyaltyService.getCustomerByPhone(event.phone);
  const replyText = event.text.toUpperCase().trim();

  // High engagement - customer actively participating
  await loyaltyService.updateEngagement(customer.email, {
    smsReplies: customer.smsReplies + 1,
    lastSMSReply: new Date(event.date),
    engagementScore: customer.engagementScore + 10
  });

  // Process loyalty commands
  switch (replyText) {
    case 'BALANCE':
      await loyaltyService.sendPointsBalance(event.phone);
      break;

    case 'REWARDS':
      await loyaltyService.sendAvailableRewards(event.phone, customer.loyaltyTier);
      break;

    case 'TIER':
      await loyaltyService.sendTierInfo(event.phone, customer);
      break;

    case 'HELP':
      await loyaltyService.sendSMSHelp(event.phone);
      break;

    case 'STOP':
    case 'UNSUBSCRIBE':
      await loyaltyService.unsubscribeFromSMS(event.phone);
      break;

    default:
      // Forward to customer service
      await loyaltyService.forwardToSupport(customer.email, {
        channel: 'sms',
        message: event.text,
        timestamp: new Date(event.date)
      });
  }
}
```

## Eventos de Contacto

### contact\_created

Acionado quando um novo contacto é adicionado ao Brevo.

**Exemplo de Payload:**

```json
{
  "event": "contact_created",
  "email": "newcustomer@example.com",
  "date": "2024-01-25 13:15:00",
  "ts": 1640992500,
  "attributes": {
    "FIRSTNAME": "John",
    "LASTNAME": "Doe",
    "LOYALTY_ID": "LYL-2024-001",
    "LOYALTY_TIER": "Bronze",
    "LOYALTY_POINTS": 0
  },
  "lists": [1, 5]
}
```

**Casos de Uso na Integração Tajo:**

- Acionar campanhas de boas-vindas
- Configurar a inscrição no programa de fidelidade
- Inicializar a jornada do cliente
- Atribuir bónus de registo

```javascript
async function handleContactCreated(event) {
  const isLoyaltyMember = event.attributes?.LOYALTY_ID;

  if (isLoyaltyMember) {
    // New loyalty member - trigger welcome flow
    await loyaltyService.triggerWelcomeFlow(event.email, {
      loyaltyId: event.attributes.LOYALTY_ID,
      tier: event.attributes.LOYALTY_TIER || 'Bronze',
      signupBonus: 500
    });

    // Award signup bonus
    await loyaltyService.awardPoints(event.email, {
      amount: 500,
      reason: 'Welcome bonus',
      type: 'signup_bonus'
    });

    // Schedule onboarding emails
    await loyaltyService.scheduleOnboardingSequence(event.email, {
      tier: event.attributes.LOYALTY_TIER,
      preferences: event.attributes
    });
  }

  // Track signup source
  await loyaltyService.trackSignupSource(event.email, {
    lists: event.lists,
    attributes: event.attributes,
    timestamp: new Date(event.date)
  });
}
```

### contact\_updated

Acionado quando as informações de um contacto são atualizadas.

**Exemplo de Payload:**

```json
{
  "event": "contact_updated",
  "email": "customer@example.com",
  "date": "2024-01-25 16:45:00",
  "ts": 1641003900,
  "updated_attributes": {
    "LOYALTY_POINTS": 1250,
    "LOYALTY_TIER": "Silver",
    "TOTAL_SPENT": 899.99
  },
  "previous_attributes": {
    "LOYALTY_POINTS": 750,
    "LOYALTY_TIER": "Bronze",
    "TOTAL_SPENT": 549.99
  }
}
```

**Casos de Uso na Integração Tajo:**

- Detetar subidas de nível
- Monitorizar alterações no saldo de pontos
- Monitorizar a completude do perfil
- Acionar campanhas específicas por nível

```javascript
async function handleContactUpdated(event) {
  const updated = event.updated_attributes;
  const previous = event.previous_attributes;

  // Check for tier upgrade
  if (updated.LOYALTY_TIER && updated.LOYALTY_TIER !== previous.LOYALTY_TIER) {
    await loyaltyService.handleTierUpgrade(event.email, {
      previousTier: previous.LOYALTY_TIER,
      newTier: updated.LOYALTY_TIER,
      pointsBalance: updated.LOYALTY_POINTS
    });

    // Send congratulations
    await loyaltyService.sendTierUpgradeEmail(event.email, {
      newTier: updated.LOYALTY_TIER,
      benefits: loyaltyService.getTierBenefits(updated.LOYALTY_TIER)
    });
  }

  // Track significant point increases
  const pointIncrease = updated.LOYALTY_POINTS - previous.LOYALTY_POINTS;
  if (pointIncrease > 0) {
    await loyaltyService.trackPointsEarned(event.email, {
      amount: pointIncrease,
      newTotal: updated.LOYALTY_POINTS,
      source: 'profile_update'
    });
  }

  // Monitor spending milestones
  if (updated.TOTAL_SPENT > previous.TOTAL_SPENT) {
    await loyaltyService.checkSpendingMilestones(event.email, {
      currentSpend: updated.TOTAL_SPENT,
      previousSpend: previous.TOTAL_SPENT
    });
  }
}
```

## Boas Práticas de Processamento de Eventos

### 1. Gestão de Idempotência

```javascript
class WebhookProcessor {
  constructor() {
    this.processedEvents = new Set();
  }

  async processEvent(event) {
    const eventKey = `${event.event}_${event.email}_${event.ts}`;

    if (this.processedEvents.has(eventKey)) {
      console.log('Duplicate event ignored:', eventKey);
      return;
    }

    this.processedEvents.add(eventKey);

    try {
      await this.handleEvent(event);
    } catch (error) {
      this.processedEvents.delete(eventKey); // Allow retry
      throw error;
    }
  }
}
```

### 2. Sequenciamento de Eventos

```javascript
async function processEventInSequence(event) {
  const customer = await loyaltyService.getCustomer(event.email);
  const lastProcessedTime = customer.lastWebhookProcessed || 0;

  // Ensure events are processed in chronological order
  if (event.ts < lastProcessedTime) {
    console.warn('Out-of-order event received, queuing for later processing');
    await loyaltyService.queueEventForLaterProcessing(event);
    return;
  }

  await handleWebhookEvent(event);

  // Update last processed timestamp
  await loyaltyService.updateCustomer(event.email, {
    lastWebhookProcessed: event.ts
  });
}
```

### 3. Processamento em Lote

```javascript
class BatchEventProcessor {
  constructor() {
    this.eventBatch = [];
    this.batchSize = 100;
    this.flushInterval = 5000; // 5 seconds

    setInterval(() => this.flushBatch(), this.flushInterval);
  }

  addEvent(event) {
    this.eventBatch.push(event);

    if (this.eventBatch.length >= this.batchSize) {
      this.flushBatch();
    }
  }

  async flushBatch() {
    if (this.eventBatch.length === 0) return;

    const batch = this.eventBatch.splice(0);

    try {
      await loyaltyService.processBatchEvents(batch);
    } catch (error) {
      console.error('Batch processing failed:', error);
      // Re-queue failed events
      this.eventBatch.unshift(...batch);
    }
  }
}
```

## Próximos Passos

- **Guia de Segurança de Webhooks** - Boas práticas de segurança
- **[Testar Webhooks](https://tajo.io/pt/docs/testing-debug/)** - Testes e depuração
- **Análise de Webhooks** - Monitorização de desempenho
- **[Integração de Plataforma](https://tajo.io/pt/docs/platform-integration/tajo-brevo-integration)** - Guia de integração completo