Envoyer les inscriptions de votre propre formulaire de newsletter vers Kit

Envoyez votre propre formulaire à Ikiform, et faites pointer un webhook Ikiform vers un relais qui fait jusqu'à trois appels à l'API v4 de Kit : créer l'abonné, l'ajouter à un formulaire Kit, et étiqueter l'endroit où il s'est inscrit. Créez-le en inactive et ajoutez-le à un formulaire dont l'incentive email est activé : Kit devrait alors envoyer sa propre confirmation, à tester une fois avec une adresse à vous, car Kit ne le documente que pour son endpoint en masse. Le relais détient la clé d'API Kit ; votre page ne la voit jamais.

Ce qui change avec Kit

Kit découpe une inscription en objets distincts. Un abonné est une personne. Un formulaire est l'endroit d'où il vient, et il porte l'e-mail de confirmation, que Kit appelle aussi incentive email : son étape de double opt-in. Un tag est une étiquette pour segmenter. L'API v4 a un endpoint pour chacun, et les endpoints du formulaire comme du tag exigent que l'abonné existe déjà. Une inscription Ikiform devient donc une courte suite d'appels, dans l'ordre :

Configurer Kit

1. Dans Kit, créez un formulaire pour ces inscriptions, par exemple « Inscription site web ». Vous ne l'intégrerez pas ; il sert à enregistrer d'où viennent les abonnés et à héberger l'incentive email.
2. Ouvrez les réglages du formulaire et activez l'incentive email si vous voulez le double opt-in. Rédigez l'e-mail et définissez où mène le lien de confirmation.
3. Trouvez l'id numérique du formulaire, dans l'application Kit ou avec l'endpoint de l'API qui liste les formulaires. Créez un tag par emplacement si vous le souhaitez, et notez leurs id.
4. Créez une clé d'API v4 dans les réglages développeur de Kit et gardez-la pour l'environnement du relais.

Le relais

Un route handler Next.js reçoit le webhook et un petit module dialogue avec Kit. Les deux mêmes fichiers tournent sur n'importe quel hébergeur Node ou edge qui fournit une URL HTTPS publique.

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 est la façon dont l'API v4 de Kit reçoit une clé d'API personnelle. OAuth sert aux applications que d'autres installent ; un relais pour votre propre liste n'en a pas besoin.
• Envoyer state: "inactive" est ce qui garde un nouvel abonné non confirmé jusqu'à son clic. Sans cela, Kit le crée en active, et l'état ne peut plus être modifié ensuite via le même endpoint.
• Le referrer de la page part chez Kit comme referrer du formulaire : Kit montre donc l'article d'où vient le lecteur.
• Le corps d'erreur de Kit va dans le 502 : le journal de livraison d'Ikiform affiche donc le message de Kit.
• Associez chaque valeur source à un id de tag dans TAGS. Une source sans tag saute le troisième appel.

Ajoutez l'URL de la route sous Webhooks dans le tableau de bord Ikiform, choisissez le formulaire de newsletter et copiez le secret whsec_ dans IKIFORM_WEBHOOK_SECRET. Chaque règle concernant l'URL et chaque réponse est dans la documentation des webhooks.

Limites de débit et nouvelles tentatives

Kit autorise 120 requêtes par fenêtre glissante de 60 secondes pour une clé d'API. Chaque inscription en coûte deux ou trois : environ 40 à 60 inscriptions par minute passent avant que Kit ne réponde 429. C'est largement suffisant pour un formulaire de pied de page, et juste le jour où un article devient viral.

Le relais répond 503 avec Retry-After quand Kit répond 429, et Ikiform attend avant de réessayer. Une nouvelle tentative rejoue toute la séquence depuis le début. C'est sans risque : la création renvoie 200 pour un abonné existant, et l'ajout de quelqu'un déjà dans le formulaire renvoie 200. La documentation des formulaires en masse de Kit indique que les personnes déjà inscrites à un formulaire ne reçoivent pas à nouveau l'incentive email ; l'endpoint unitaire ne le précise pas, testez donc une nouvelle tentative avec une adresse à vous. Votre propre serveur montre comment enregistrer chaque webhook-id si vous préférez sauter les nouvelles tentatives déjà traitées.

Pièges

• Les champs personnalisés doivent exister d'abord. Si vous ajoutez fields à l'appel de création, utilisez la clé de chaque champ, comme last_name, et créez le champ dans Kit avant de l'envoyer.
• Les abonnés actifs restent actifs. Comme la création ne change jamais l'état d'un abonné existant, un lecteur confirmé qui s'inscrit à nouveau n'a pas à reconfirmer.
• Les lecteurs désinscrits. Un lecteur désinscrit qui s'inscrit à nouveau existe déjà : la création renvoie 200 et ne change pas son état. Voyez dans Kit comment vous voulez les traiter.
• Un formulaire, plusieurs emplacements. Utilisez un seul formulaire Kit pour le site et des tags pour les emplacements. Plusieurs formulaires Kit, ce sont plusieurs incentive emails à garder synchronisés.
• Pas d'e-mail de la part d'Ikiform. Ikiform n'envoie pas d'e-mail à la personne qui remplit le formulaire. Les e-mails de notification vont uniquement à vous et à votre équipe : il n'y a donc ni réponse automatique, ni e-mail de confirmation, ni double opt-in. Envoyez-les depuis votre outil d'e-mailing, déclenché par un webhook.

Vérifiez que tout fonctionne

1. Choisissez Send test sur l'endpoint dans Ikiform. La livraison affiche 204, et rien ne change dans Kit.
2. Abonnez-vous sur votre page avec une adresse à vous. La livraison affiche 204.
3. Dans Kit, l'abonné apparaît dans votre formulaire comme non confirmé, avec le tag de l'emplacement.
4. L'incentive email arrive. Cliquez sur le lien et l'abonné devient confirmé.
5. Abonnez-vous à nouveau avec la même adresse. La livraison affiche 204 et aucun second incentive email n'arrive.
6. Mettez un KIT_FORM_ID erroné un instant. La livraison affiche 502 avec le message 404 de Kit.

Questions