技能 编程开发 Attio Webhook实时事件处理

Attio Webhook实时事件处理

v20260423
attio-webhooks-events
本技能用于实现Attio v2的Webhook功能,支持实时订阅CRM中的各类事件(如记录创建、任务完成等)。核心功能包括:配置事件订阅、使用HMAC-SHA256进行签名验证以确保数据安全、按对象或属性进行事件过滤,以及处理幂等性,确保数据同步的准确性和可靠性。
获取技能
379 次下载
概览

Attio Webhooks & Events

Overview

Attio v2 webhooks deliver real-time CRM event notifications to your HTTPS endpoint. Subscribe to record, list-entry, note, and task events with optional object or attribute filters to reduce volume. Webhooks are managed via POST /v2/webhooks and verified with HMAC-SHA256 signatures using a timestamp-prefixed payload.

Webhook Registration

const webhook = await fetch("https://api.attio.com/v2/webhooks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ATTIO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target_url: "https://yourapp.com/webhooks/attio",
    subscriptions: [
      { event_type: "record.created" },
      { event_type: "record.updated", filter: { object: { $eq: "deals" } } },
      { event_type: "note.created" },
      { event_type: "task.completed" },
    ],
  }),
});

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyAttioSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-attio-signature"] as string;
  const timestamp = req.headers["x-attio-timestamp"] as string;
  const age = Date.now() - parseInt(timestamp) * 1000;
  if (age > 300_000) return res.status(401).json({ error: "Timestamp too old" });
  const payload = `${timestamp}.${req.body.toString()}`;
  const expected = crypto.createHmac("sha256", process.env.ATTIO_WEBHOOK_SECRET!)
    .update(payload).digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  next();
}

Event Handler

import express from "express";
const app = express();

app.post("/webhooks/attio", express.raw({ type: "application/json" }), verifyAttioSignature, (req, res) => {
  const event = JSON.parse(req.body.toString());
  res.status(200).json({ received: true });

  switch (event.event_type) {
    case "record.created":
      syncRecordToCRM(event.object?.api_slug, event.record?.id?.record_id); break;
    case "record.updated":
      reindexRecord(event.object?.api_slug, event.record?.id?.record_id); break;
    case "note.created":
      forwardToNotionSync(event.id.event_id); break;
    case "task.completed":
      closeProjectTask(event.id.event_id); break;
  }
});

Event Types

EventPayload FieldsUse Case
record.createdobject.api_slug, record.record_id, actorSync new contacts/deals to external CRM
record.updatedobject.api_slug, record.record_id, attributeRe-index changed records
note.createdevent_id, actor, recordForward meeting notes to Notion
task.completedevent_id, actor, recordClose linked project management tasks
list-entry.createdlist.api_slug, entry.entry_idTrigger pipeline stage automation

Retry & Idempotency

const processed = new Set<string>();

async function handleIdempotent(event: { id: { event_id: string }; event_type: string }) {
  const eventId = event.id.event_id;
  if (processed.has(eventId)) return;
  await routeEvent(event);
  processed.add(eventId);
  if (processed.size > 10_000) {
    const entries = Array.from(processed);
    entries.slice(0, entries.length - 10_000).forEach((id) => processed.delete(id));
  }
}

Error Handling

IssueCauseFix
Signature mismatchBody parsed before raw verificationUse express.raw(), verify raw body
Duplicate eventsAttio retry on timeoutTrack event_id in Redis or DB
Missed eventsHandler returns non-200Return 200 immediately, process async
Too many eventsNo subscription filteringAdd filter clauses to subscriptions

Resources

Next Steps

See attio-security-basics.

信息
分类 编程开发
名称 attio-webhooks-events
版本 v20260423
大小 4.57KB
更新时间 2026-04-28
语言