NueForm

API Webhooks

Configurer des webhooks par formulaire et globaux pour les notifications de réponses en temps réel.

Les webhooks vous permettent de recevoir des notifications HTTP POST en temps réel lorsque des formulaires reçoivent de nouvelles soumissions. NueForm prend en charge deux niveaux de webhooks :

  • Webhooks de formulaire -- Une URL unique par formulaire qui reçoit les soumissions pour ce formulaire spécifique.
  • Webhooks globaux -- Jusqu'à 5 URL qui reçoivent les soumissions de tous vos formulaires.

Les webhooks nécessitent un abonnement Pro ou supérieur. Toute tentative d'utilisation des points d'accès webhook avec un abonnement gratuit renverra une erreur 403.

Tous les corps de requête et de réponse utilisent des noms de champs en snake_case.

Endpoints
GET/api/v1/forms/:id/webhooksPUT/api/v1/forms/:id/webhooksGET/api/v1/webhooksPUT/api/v1/webhooksGET/api/v1/webhooks/secretPOST/api/v1/webhooks/secret

Obtenir le webhook du formulaire

GET/api/v1/forms/:id/webhooks

Récupère l'URL webhook configurée pour un formulaire spécifique.

Paramètres de chemin

idstringrequis

L'identifiant du formulaire

Si aucun webhook n'est configuré, webhook_url sera null.

Réponse

json
{
  "webhook_url": "https://example.com/hooks/nueform"
}

Exemples de code

bash
curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Configurer le webhook du formulaire

PUT/api/v1/forms/:id/webhooks

Définit ou supprime l'URL webhook pour un formulaire spécifique. Lorsqu'une soumission est reçue, NueForm enverra un HTTP POST à cette URL avec les données de la réponse.

Paramètres de chemin

idstringrequis

L'identifiant du formulaire

Corps de la requête

urlstring or nullrequis

L'URL du webhook. Doit être une URL valide. Définir à null pour supprimer le webhook.

Exemple de requête

json
{
  "url": "https://example.com/hooks/nueform"
}

Pour supprimer un webhook :

json
{
  "url": null
}

Réponse

json
{
  "webhook_url": "https://example.com/hooks/nueform"
}

Exemples de code

bash
curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/nueform" }'

Lister les webhooks globaux

GET/api/v1/webhooks

Récupère tous les webhooks globaux configurés pour votre compte. Les webhooks globaux se déclenchent pour chaque soumission de formulaire dans tous vos formulaires.

Réponse

json
{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Exemples de code

bash
curl -X GET "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Configurer les webhooks globaux

PUT/api/v1/webhooks

Remplace tous les webhooks globaux par le tableau fourni. Vous pouvez configurer jusqu'à 5 webhooks globaux. Chaque webhook peut être activé ou désactivé individuellement.

Corps de la requête

webhooksarrayrequis

Tableau d'objets webhook (max 5)

Exemple de requête

json
{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Réponse

json
{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Exemples de code

bash
curl -X PUT "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://example.com/hooks/all-forms", "enabled": true },
      { "url": "https://backup.example.com/hooks/nueform", "enabled": false }
    ]
  }'

Obtenir le secret webhook

GET/api/v1/webhooks/secret

Récupère votre secret de signature webhook. Si aucun secret n'existe encore, un est automatiquement généré. Le secret est une chaîne hexadécimale de 64 caractères dérivée de 32 octets aléatoires.

Utilisez ce secret pour vérifier que les requêtes webhook entrantes proviennent réellement de NueForm en validant la signature HMAC-SHA256 dans l'en-tête X-NueForm-Signature.

Vérification des signatures

Lorsque NueForm envoie un webhook, il inclut un en-tête X-NueForm-Signature contenant un condensé hexadécimal HMAC-SHA256 du corps de la requête. Vérifiez-le dans votre gestionnaire de webhook pour garantir l'authenticité.

Réponse

json
{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

Exemples de vérification de signature

javascript
const crypto = require("crypto");

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Exemples de code

bash
curl -X GET "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

Régénérer le secret webhook

POST/api/v1/webhooks/secret

Génère un nouveau secret de signature webhook, remplaçant l'existant. Après régénération, toutes les livraisons de webhook seront signées avec le nouveau secret.

Après régénération, mettez à jour vos récepteurs de webhook immédiatement pour utiliser le nouveau secret. Les requêtes signées avec l'ancien secret échoueront à la vérification.

Réponse

json
{
  "secret": "f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

Exemples de code

bash
curl -X POST "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

Format de la charge utile webhook

Lorsqu'un formulaire reçoit une soumission, NueForm envoie une requête POST à vos URL webhook configurées avec la charge utile suivante.

Le champ event identifie le type d'événement, et l'objet response contient les données complètes de la soumission, y compris toutes les réponses.

En-têtes

Content-Typeapplication/json

Type de contenu du corps de la requête

X-NueForm-Signaturestring

Condensé hexadécimal HMAC-SHA256 du corps de la requête

X-NueForm-Eventstring

Event type (e.g., response.submitted)

Exemple de charge utile

json
{
  "event": "response.submitted",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "form_title": "Customer Feedback Survey",
  "response": {
    "id": "667a1b2c3d4e5f6a7b8c9d01",
    "submitted_at": "2026-02-27T15:42:00.000Z",
    "completed_at": "2026-02-27T15:45:30.000Z",
    "answers": [
      {
        "question_id": "66a1b2c3d4e5f6a7b8c9d001",
        "question_title": "What is your name?",
        "value": "Jane Smith"
      }
    ]
  }
}

Réponses d'erreur

Réponses d'erreur standard renvoyées par les points d'accès webhook.

Codes d'erreur

400Bad Request

Format d'URL invalide, maximum de 5 webhooks globaux dépassé ou champs obligatoires manquants

401Unauthorized

Clé API manquante ou invalide

403Forbidden

Les webhooks nécessitent un abonnement Pro ou supérieur

404Not Found

Formulaire introuvable

500Server Error

Erreur interne du serveur

Exemple d'erreur

json
{
  "error": "Webhooks require a Pro plan or higher"
}
Dernière mise à jour : 6 avril 2026