---
title: "Créer un endpoint de webhook"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Créer un endpoint de webhook

`POST /webhooks`

## Request

- Base URL: `https://api.swipify.fr/api/v1`
- URL: `https://api.swipify.fr/api/v1/webhooks`
- Auth: API key in header `X-API-Key`

Abonne une URL `https` à des événements. Renvoie le `secret` de signature EN CLAIR **une seule fois** (à stocker côté abonné). L'URL est validée (https + anti-SSRF) puis immuable. Scope requis : `webhooks:write`.

## Request body

- WebhookCreate
  - `url` string, uri, required: URL https de destination (http interdit ; IP privées/loopback/métadonnées refusées, anti-SSRF).
  - `events` WebhookEventType[], required
  - `description` string, nullable
  - `active` boolean

## Response `201`

Endpoint créé (secret renvoyé une seule fois)

- WebhookCreated: Endpoint de webhook sortant (le secret n'est jamais renvoyé après la création).
  - `id` integer
  - `url` string, uri
  - `events` WebhookEventType[]
  - `description` string, nullable
  - `active` boolean
  - `secretPrefix` string: Préfixe du secret (indice d'identification ; jamais le secret complet).
  - `lastTriggeredAt` string, date-time, nullable
  - `createdAt` string, date-time
  - `secret` string: Secret de signature EN CLAIR, renvoyé UNE SEULE FOIS. À stocker côté abonné pour vérifier l'en-tête Swipify-Signature.

## Other responses

- `400`: Données invalides
- `401`: Échec d'authentification : clé API manquante (`missing_api_key`) ou invalide/révoquée/expirée (`invalid_api_key`). Le client doit présenter une clé valide.
- `403`: Clé authentifiée mais non autorisée : scope insuffisant pour cette route (`scope_required`), ou organisation sans abonnement Pro actif (`pro_required`). `GET /me` reste accessible sans Pro pour diagnostiquer la clé.
- `409`: Conflit (ressource déjà existante, limite atteinte ; sur les routes idempotentes, Idempotency-Key déjà en cours)
- `429`: Trop de requêtes (quota de la clé API, ou de l'organisation pour les analyses de document, dépassé pour la fenêtre courante)

---

[API](https://skmtc.dev/swipify/apis/swipify-api-publique.md) · [All operations](https://skmtc.dev/swipify/apis/swipify-api-publique/llms.txt) · [OpenAPI document](https://skmtc.dev/swipify/apis/swipify-api-publique/revisions/44c17201b479?raw)