Kirim pendaftaran dari formulir newsletter Anda sendiri ke Kit

Kirim formulir Anda sendiri ke Ikiform, dan arahkan webhook Ikiform ke relay yang melakukan hingga tiga panggilan API Kit v4: membuat subscriber, menambahkannya ke formulir Kit, dan memberi tag tempat mereka mendaftar. Buat mereka sebagai inactive dan tambahkan ke formulir yang incentive email-nya aktif, maka Kit seharusnya mengirim konfirmasinya sendiri, yang perlu Anda uji sekali dengan alamat milik Anda karena Kit hanya mendokumentasikannya untuk endpoint bulk. Relay memegang API key Kit; halaman Anda tidak pernah melihatnya.

Apa yang berbeda dengan Kit

Kit memecah pendaftaran menjadi objek-objek terpisah. Subscriber adalah orang. Form adalah asal mereka, dan membawa email konfirmasi, yang juga disebut Kit sebagai incentive email: langkah double opt-in-nya. Tag adalah label untuk segmentasi. API v4 punya satu endpoint untuk masing-masing, dan endpoint form maupun tag butuh subscriber yang sudah ada lebih dulu. Jadi satu pendaftaran Ikiform menjadi rangkaian panggilan singkat, berurutan:

Siapkan Kit

1. Di Kit, buat formulir untuk pendaftaran ini, misalnya "Pendaftaran website". Anda tidak akan meng-embed-nya; formulir itu adalah catatan asal subscriber dan tempat incentive email berada.
2. Buka pengaturan formulir dan aktifkan incentive email jika Anda menginginkan double opt-in. Tulis email-nya dan atur ke mana tautan konfirmasi mengarah.
3. Temukan ID numerik formulir, di aplikasi Kit atau dengan endpoint list forms di API. Buat tag per penempatan jika Anda mau, dan catat ID-nya.
4. Buat API key v4 di pengaturan developer Kit dan simpan untuk environment relay.

Relay

Route handler Next.js menerima webhook dan modul kecil berkomunikasi dengan Kit. Dua file yang sama berjalan di host Node atau edge mana pun yang memberi Anda URL HTTPS publik.

const KIT = "https://api.kit.com/v4";

const TAGS: Record<string, number> = {
  footer: 1111111,
  post: 2222222,
};

function call(path: string, body: Record<string, unknown>) {
  return fetch(`${KIT}${path}`, {
    method: "POST",
    headers: {
      "X-Kit-Api-Key": process.env.KIT_API_KEY!,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify(body),
  });
}

export async function addToKit(signup: { email: string; firstName?: string; source: string; referrer?: string }) {
  const created = await call("/subscribers", {
    email_address: signup.email,
    first_name: signup.firstName ?? null,
    state: "inactive",
  });
  if (!created.ok) return created;

  const joined = await call(`/forms/${process.env.KIT_FORM_ID}/subscribers`, {
    email_address: signup.email,
    referrer: signup.referrer ?? null,
  });
  if (!joined.ok) return joined;

  const tag = TAGS[signup.source];
  if (!tag) return joined;
  return call(`/tags/${tag}/subscribers`, { email_address: signup.email });
}

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import { addToKit } from "@/lib/kit";

export async function POST(request: Request) {
  const payload = await request.text();
  let event;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  if (event.type !== "submission.created") return new Response(null, { status: 204 });

  const { email, first_name, consent, source } = event.data.fields;
  if (consent !== true || typeof email !== "string") return new Response("Skipped", { status: 200 });

  const answer = await addToKit({
    email,
    firstName: typeof first_name === "string" ? first_name : undefined,
    source: typeof source === "string" ? source : "unknown",
    referrer: typeof event.data.meta.referrer === "string" ? event.data.meta.referrer : undefined,
  });

  if (answer.status === 429) return new Response("Kit rate limit", { status: 503, headers: { "retry-after": "60" } });
  if (!answer.ok) return new Response(`Kit answered ${answer.status}: ${await answer.text()}`, { status: 502 });
  return new Response(null, { status: 204 });
}

IKIFORM_WEBHOOK_SECRET=whsec_...
KIT_API_KEY=your-v4-api-key
KIT_FORM_ID=1234567

• X-Kit-Api-Key adalah cara API v4 Kit menerima API key pribadi. OAuth untuk aplikasi yang dipasang orang lain; relay untuk daftar Anda sendiri tidak membutuhkannya.
• Mengirim state: "inactive" adalah yang menjaga subscriber baru tetap belum terkonfirmasi sampai mereka mengklik. Hilangkan itu dan Kit membuat mereka sebagai active, dan state tidak bisa diubah nanti lewat endpoint yang sama.
• Referrer halaman dikirim ke Kit sebagai referrer formulir, jadi Kit menampilkan artikel asal pembaca.
• Body error dari Kit dimasukkan ke 502, jadi log pengiriman di Ikiform menampilkan pesan Kit sendiri.
• Petakan setiap nilai source ke ID tag di TAGS. Source tanpa tag melewati panggilan ketiga.

Tambahkan URL route di Webhooks di dashboard Ikiform, pilih formulir newsletter, dan salin secret whsec_ ke IKIFORM_WEBHOOK_SECRET. Setiap aturan untuk URL dan setiap jawaban ada di dokumentasi webhook.

Rate limit dan percobaan ulang

Kit mengizinkan 120 request per 60 detik bergulir untuk satu API key. Setiap pendaftaran memakai dua atau tiga, jadi kira-kira 40 sampai 60 pendaftaran per menit muat sebelum Kit menjawab 429. Itu lebih dari cukup untuk formulir footer, dan mepet di hari sebuah artikel viral.

Relay menjawab 503 dengan Retry-After saat Kit menyatakan 429, dan Ikiform menunggu sebelum mencoba lagi. Percobaan ulang menjalankan seluruh rangkaian dari awal. Itu aman: create mengembalikan 200 untuk subscriber yang sudah ada, dan menambahkan orang yang sudah ada di formulir mengembalikan 200. Dokumentasi bulk form Kit menyatakan orang yang sudah ada di formulir tidak mendapat incentive email lagi; endpoint tunggal tidak menyebutkannya, jadi uji percobaan ulang dengan alamat milik Anda. Server Anda sendiri menunjukkan cara mencatat setiap webhook-id jika Anda lebih suka melewati percobaan ulang yang sudah selesai.

Hal yang sering menjebak

• Custom field harus ada lebih dulu. Jika Anda menambahkan fields ke panggilan create, gunakan key setiap field, seperti last_name, dan buat field itu di Kit sebelum Anda mengirimnya.
• Subscriber aktif tetap aktif. Karena create tidak pernah mengubah state subscriber yang sudah ada, pembaca terkonfirmasi yang mendaftar lagi tidak diminta mengonfirmasi lagi.
• Pembaca yang sudah berhenti berlangganan. Pembaca yang sudah unsubscribe lalu mendaftar lagi sudah ada, jadi create mengembalikan 200 dan tidak mengubah state-nya. Tentukan di Kit bagaimana Anda ingin menangani mereka.
• Satu formulir, banyak penempatan. Gunakan satu formulir Kit untuk website dan tag untuk penempatan. Beberapa formulir Kit berarti beberapa incentive email yang harus diselaraskan.
• Tidak ada email dari Ikiform. Ikiform tidak mengirim email ke orang yang mengisi formulir. Email notifikasi hanya dikirim ke Anda dan tim Anda, jadi tidak ada autoresponder, email konfirmasi, atau double opt-in. Kirim semua itu dari alat email Anda, dipicu oleh webhook.

Pastikan berfungsi

1. Pilih Send test di endpoint di Ikiform. Pengiriman menampilkan 204, dan tidak ada yang berubah di Kit.
2. Berlangganan di halaman Anda dengan alamat milik Anda. Pengiriman menampilkan 204.
3. Di Kit, subscriber tampil di formulir Anda sebagai belum terkonfirmasi, dengan tag penempatannya.
4. Incentive email tiba. Klik tautannya dan subscriber menjadi terkonfirmasi.
5. Berlangganan lagi dengan alamat yang sama. Pengiriman menampilkan 204 dan tidak ada incentive email kedua.
6. Atur KIT_FORM_ID yang salah sejenak. Pengiriman menampilkan 502 dengan pesan 404 dari Kit.

Pertanyaan