Webhooks

FonctionnementCopier le lien

Un webhook est une URL à vous que Nudge appelle en POST quand quelque chose se produit dans votre espace. Servez-vous-en pour pousser les nouveaux leads vers Zapier, Make, n8n, votre CRM ou votre backend, sans interroger Nudge en boucle.

• Un webhook = une URL + les événements écoutés + un secret de signature optionnel.
• Vous pouvez créer plusieurs webhooks, chacun avec ses événements.
• Chaque livraison est un corps JSON avec le nom de l'événement, un horodatage et les données. Voir la référence des événements.

Créer un webhookCopier le lien

Il vous faut la permission Manage API keys & webhooks (api.manage) pour créer, modifier ou supprimer un webhook, et l'accès à la page Intégrations (integrations.manage) pour atteindre le panneau.

Chaque webhook de la liste a un interrupteur pour le mettre en pause ou le réactiver, une icône en forme d'œil qui ouvre ses Journaux de livraison, et un bouton de suppression.

Vous pouvez aussi gérer les webhooks depuis un assistant IA avec les outils MCP integrations__create_webhook, integrations__update_webhook, integrations__delete_webhook, integrations__list_webhooks et integrations__list_webhook_logs (voir la référence des outils MCP).

Exigences sur l'URLCopier le lien

À l'enregistrement, Nudge refuse toute URL qui :

• n'utilise pas https:// ;
• pointe vers localhost, un nom en .local ou .localhost, un hôte sans point, ou une adresse privée, de boucle locale ou link-local (par exemple 10.x.x.x, 192.168.x.x, 169.254.x.x, ::1).

À la livraison, Nudge ne suit pas les redirections : un endpoint qui répond 301 ou 302 échoue. Indiquez l'URL finale.

À quoi ressemble une livraisonCopier le lien

POST /hooks/nudge HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Nudge-Webhook/1.0
X-Nudge-Signature: sha256=5d41402abc4b2a76b9719d911017c592...

{"event":"lead_created","timestamp":"2026-11-02T09:14:07.512Z","data":{"id":"6f0c…","email":"jane@example.com","lead_score":72,"form_id":"a1b2…"},"organization_id":"9e8d…"}

Vérifier la signatureCopier le lien

Calculez un HMAC-SHA256 du corps brut de la requête, tel que reçu, avec votre secret de signature comme clé. Encodez-le en hexadécimal, préfixez-le par sha256= et comparez-le à X-Nudge-Signature avec une comparaison en temps constant. Rejetez la requête s'ils diffèrent.

Hachez toujours les octets bruts. Si votre framework analyse d'abord le JSON et que vous le resérialisez, les espaces ou l'ordre des clés peuvent changer et la signature ne correspondra plus.

import crypto from 'node:crypto'
import express from 'express'

const app = express()
const SECRET = process.env.NUDGE_WEBHOOK_SECRET

// Gardez le corps brut : la signature est calculée dessus.
app.post('/hooks/nudge', express.raw({ type: 'application/json' }), (req, res) => {
  const received = req.get('X-Nudge-Signature') || ''
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex')

  const ok = received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  if (!ok) return res.status(401).send('Invalid signature')

  const { event, data } = JSON.parse(req.body.toString('utf8'))
  if (event === 'lead_created') {
    // Confiez le travail à une file et répondez vite.
    console.log('New lead', data.email, data.lead_score)
  }
  res.sendStatus(200)
})

app.listen(3000)

Le payload porte un timestamp. Pour limiter les rejeux, vous pouvez aussi rejeter les livraisons trop anciennes et ignorer un identifiant de lead déjà traité.

Livraison, délais et nouvelles tentativesCopier le lien

• Nudge envoie chaque événement une seule fois, juste après qu'il s'est produit, à chaque webhook actif abonné.
• Votre endpoint a 10 secondes pour répondre. Au-delà, la livraison est abandonnée.
• Dans les journaux de livraison, un statut 2xx apparaît comme un succès. Les autres statuts, les délais dépassés et les erreurs de connexion apparaissent comme des échecs.
• Il n'y a pas de nouvelle tentative automatique. Une livraison échouée n'est pas renvoyée. Si vous ne pouvez pas vous permettre de perdre un lead, répondez vite (mettez le travail en file, puis renvoyez 200) et faites un rattrapage depuis Nudge quand votre endpoint a été indisponible, par exemple avec l'outil MCP contacts__list_contacts.
• Les livraisons d'un même événement vers plusieurs webhooks ne sont pas ordonnées, et un webhook lent ne retarde pas les autres.
• Les leads de test (aperçu et mode test) ne sont jamais livrés.

Journaux de livraisonCopier le lien

Cliquez sur l'icône en forme d'œil d'un webhook pour ouvrir ses Journaux de livraison : les 20 dernières tentatives, chacune avec l'événement, l'heure et le statut HTTP renvoyé par votre endpoint (ou Erreur s'il n'a pas pu être joint). Les journaux sont supprimés avec le webhook.

DépannageCopier le lien