Webhook

Recevez des webhooks de n'importe quel service en configurant un webhook personnalisé.

Aperçu

Le bloc Webhook générique vous permet de recevoir des webhooks depuis n'importe quel service externe. C'est un déclencheur flexible qui peut traiter n'importe quelle charge utile JSON, ce qui le rend idéal pour l'intégration avec des services qui n'ont pas de bloc Ekinox dédié.

Utilisation de base

Mode de transmission simple

Sans définir un format d'entrée, le webhook transmet l'intégralité du corps de la requête tel quel :

curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret" \
  -d '{
    "message": "Test webhook trigger",
    "data": {
      "key": "value"
    }
  }'

Accédez aux données dans les blocs en aval en utilisant :

<webhook1.message> → "Test webhook trigger"
<webhook1.data.key> → "value"

Format d'entrée structuré (optionnel)

Définissez un schéma d'entrée pour obtenir des champs typés et activer des fonctionnalités avancées comme les téléchargements de fichiers :

Configuration du format d'entrée :

[
  { "name": "message", "type": "string" },
  { "name": "priority", "type": "number" },
  { "name": "documents", "type": "files" }
]

Requête webhook :

curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret" \
  -d '{
    "message": "Invoice submission",
    "priority": 1,
    "documents": [
      {
        "type": "file",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "name": "invoice.pdf",
        "mime": "application/pdf"
      }
    ]
  }'

{
  "documents": [
    {
      "type": "file",
      "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...",
      "name": "screenshot.png",
      "mime": "image/png"
    }
  ]
}

Taille maximale : 20 Mo par fichier
Format : URL de données standard avec encodage base64
Stockage : Les fichiers sont téléchargés dans un stockage d'exécution sécurisé

2. Références URL

Pour transmettre des URL de fichiers existants :

{
  "documents": [
    {
      "type": "url",
      "data": "https://example.com/files/document.pdf",
      "name": "document.pdf",
      "mime": "application/pdf"
    }
  ]
}

Accès aux fichiers dans les blocs en aval

Les fichiers sont traités en objets UserFile avec les propriétés suivantes :

{
  id: string,          // Unique file identifier
  name: string,        // Original filename
  url: string,         // Presigned URL (valid for 5 minutes)
  size: number,        // File size in bytes
  type: string,        // MIME type
  key: string,         // Storage key
  uploadedAt: string,  // ISO timestamp
  expiresAt: string    // ISO timestamp (5 minutes)
}

Accès dans les blocs :

<webhook1.documents[0].url> → URL de téléchargement
<webhook1.documents[0].name> → "invoice.pdf"
<webhook1.documents[0].size> → 524288
<webhook1.documents[0].type> → "application/pdf"

Exemple complet de téléchargement de fichier

# Create a base64-encoded file
echo "Hello World" | base64
# SGVsbG8gV29ybGQK

# Send webhook with file
curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret" \
  -d '{
    "subject": "Document for review",
    "attachments": [
      {
        "type": "file",
        "data": "data:text/plain;base64,SGVsbG8gV29ybGQK",
        "name": "sample.txt",
        "mime": "text/plain"
      }
    ]
  }'

Authentification

Configurer l'authentification (facultatif)

Dans la configuration du webhook :

Activez "Exiger l'authentification"
Définissez un jeton secret
Choisissez le type d'en-tête :
- En-tête personnalisé : X-Ekinox-Secret: your-token
- Autorisation Bearer : Authorization: Bearer your-token

Utilisation de l'authentification

# With custom header
curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret-token" \
  -d '{"message": "Authenticated request"}'

# With bearer token
curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"message": "Authenticated request"}'

Bonnes pratiques

Utilisez le format d'entrée pour la structure : définissez un format d'entrée lorsque vous connaissez le schéma attendu. Cela fournit :
- Validation de type
- Meilleure autocomplétion dans l'éditeur
- Capacités de téléchargement de fichiers
Authentification : activez toujours l'authentification pour les webhooks de production afin d'empêcher les accès non autorisés.
Limites de taille de fichier : gardez les fichiers sous 20 Mo. Pour les fichiers plus volumineux, utilisez plutôt des références URL.
Expiration des fichiers : les fichiers téléchargés ont des URL d'expiration de 5 minutes. Traitez-les rapidement ou stockez-les ailleurs si vous en avez besoin plus longtemps.
Gestion des erreurs : le traitement des webhooks est asynchrone. Vérifiez les journaux d'exécution pour les erreurs.
Tests : utilisez le bouton "Tester le webhook" dans l'éditeur pour valider votre configuration avant le déploiement.

Cas d'utilisation

Soumissions de formulaires : recevez des données de formulaires personnalisés avec téléchargements de fichiers
Intégrations tierces : connectez-vous à des services qui envoient des webhooks (Stripe, GitHub, etc.)
Traitement de documents : acceptez des documents de systèmes externes pour traitement
Notifications d'événements : recevez des données d'événements de diverses sources
API personnalisées : créez des points de terminaison API personnalisés pour vos applications

Remarques

Catégorie : triggers
Type : generic_webhook
Support de fichiers : disponible via la configuration du format d'entrée
Taille maximale de fichier : 20 Mo par fichier