---
title: "事件类型参考"
description: "Brevo 全部 webhook 事件类型的完整参考指南，附 Tajo 忠诚度平台集成示例"
url: https://tajo.io/zh-cn/docs/webhooks-events/event-types/
markdown: https://tajo.io/zh-cn/docs/webhooks-events/event-types.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# 事件类型参考

本参考文档覆盖 Brevo 中所有可用的 webhook 事件类型，并针对 Tajo 忠诚度平台集成给出具体示例。

## 邮件事件

### delivered

邮件成功投递到收件人邮箱时触发。

**载荷示例：**

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

**Tajo 集成用例：**

- 更新客户档案中的投递成功率
- 为忠诚度营销活动触发后续动作
- 按会员等级跟踪邮件投递表现

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

收件人打开邮件时触发（通过跟踪像素加载判定）。

**载荷示例：**

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

**Tajo 集成用例：**

- 提升客户的互动分数
- 跟踪忠诚度营销活动效果
- 触发基于行为的奖励
- 个性化后续沟通

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

收件人点击邮件中的链接时触发。

**载荷示例：**

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

**Tajo 集成用例：**

- 跟踪转化漏斗各环节的表现
- 为点击行为发放奖励积分
- 识别高价值内容
- 优化从邮件到网站的流程

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

邮件退信（临时失败）或硬退信（永久失败）时触发。

**载荷示例：**

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

**Tajo 集成用例：**

- 更新邮箱有效性状态
- 切换到备用沟通渠道
- 清理客户数据库
- 阻止继续向无效地址发送

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

收件人将邮件标记为垃圾邮件时触发。

**载荷示例：**

```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"]
}
```

**Tajo 集成用例：**

- 立即停止邮件沟通
- 复查并改进邮件内容
- 按客户细分分析垃圾邮件投诉规律
- 采用更严格的订阅确认流程

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

## 短信事件

### sms\_delivered

短信成功投递到收件人手机时触发。

**载荷示例：**

```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."
}
```

**Tajo 集成用例：**

- 确认短信投递成功
- 跟踪短信互动率
- 校验手机号码准确性
- 监控运营商侧的投递表现

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

短信投递失败时触发。

**载荷示例：**

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

**Tajo 集成用例：**

- 更新手机号码有效性
- 切换到邮件通知
- 清理手机号码数据库
- 提醒客服团队进行人工核验

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

收件人回复短信时触发。

**载荷示例：**

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

**Tajo 集成用例：**

- 处理忠诚度计划指令
- 处理客服相关请求
- 更新沟通偏好
- 触发自动回复消息

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

## 联系人事件

### contact\_created

新联系人添加到 Brevo 时触发。

**载荷示例：**

```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]
}
```

**Tajo 集成用例：**

- 触发欢迎营销活动
- 为客户完成忠诚度计划注册
- 初始化客户旅程
- 发放注册奖励

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

联系人信息更新时触发。

**载荷示例：**

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

**Tajo 集成用例：**

- 检测会员等级升级
- 跟踪积分余额变化
- 监控客户资料的完整度
- 触发面向特定等级的营销活动

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

## 事件处理最佳实践

### 1. 幂等性处理

```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. 事件排序

```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. 批量处理

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

## 后续步骤

- **Webhook 安全指南**：安全最佳实践
- **[测试 Webhook](https://tajo.io/zh-cn/docs/testing-debug/)**：测试与调试
- **Webhook 分析**：性能监控
- **[平台集成](https://tajo.io/zh-cn/docs/platform-integration/tajo-brevo-integration)**：完整集成指南