PATCH/v1/webhooks/{webhook_id}

Modifier un webhook

update_webhook

Modifie l’URL, la description, les abonnements, l’accès, les filtres, les en-têtes personnalisés, l’autorisation sortante et l’état d’activation. active: true active le webhook et lève la pause : les livraisons accumulées partent dans l’ordre. active: false désactive le webhook et annule les livraisons en attente. headers remplace toute la liste des en-têtes personnalisés ; un élément sans value conserve la valeur précédente de l’en-tête du même nom. auth: null et data_profile_id: null suppriment l’autorisation sortante et le profil de données.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de chemin

webhook_idintegerobligatoire

Paramètres d’en-tête

Idempotency-Keystring
Clé permettant de réessayer une écriture sans risque : de 1 à 255 caractères ASCII imprimables ; un UUID v4 par opération logique est recommandé. Une nouvelle tentative avec la même clé dans les 24 heures n’exécute pas l’opération une seconde fois : elle renvoie la réponse enregistrée (statut, en-têtes et corps) avec l’en-tête Idempotency-Replayed: true. La même clé avec une méthode, un chemin, un Content-Type ou un corps différents renvoie 409 api.idempotency_mismatch ; tant que la première requête est en cours, 409 api.idempotency_in_progress avec Retry-After: 1. Après une réponse 5xx ou 429, la clé est libérée, et une nouvelle tentative exécute de nouveau l’opération. La clé est propre à l’organisation et à l’appelant (clé API, utilisateur ou clé de source personnalisée).
length ≥ 1, length ≤ 255

Corps de la requête

application/json

Objet : WebhookUpdate

urlstring | null
length ≤ 2048
descriptionstring | null
length ≤ 200
eventsarray of WebhookEventFilter | null
items ≥ 1
activeboolean | null
rolestring | null
Valeurs autorisées: admineditorviewernull
data_profile_idinteger | null
null supprime le profil de données.
collection_idsarray of integer | null
Collections du webhook. Une liste vide signifie toutes les collections accessibles au rôle et au profil de données ; l’absence de valeur ou null les laisse inchangées. Une clé elle-même limitée à des collections ne voit et ne modifie que les webhooks dont les collections figurent dans sa liste (les autres webhooks renvoient 404 webhooks.not_found). Une liste vide ou une collection hors de sa liste renvoie 403 webhooks.collections_outside_key.
items ≤ 200
tagsarray of string | null
items ≤ 50
payloadstring | null
Valeurs autorisées: fullthinnull
headersarray of WebhookHeaderInput | null
items ≤ 10
authWebhookAuthInput | null
null supprime l’autorisation sortante.

Réponses

200Réponse réussie

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.
Idempotency-Replayed
true signifie que la réponse a été rejouée à partir de celle enregistrée pour cette Idempotency-Key : l’opération ne s’est pas exécutée une seconde fois.

application/json

Objet : WebhookEndpoint

idintegerobligatoire
urlstringobligatoire
descriptionstringobligatoire
eventsarray of WebhookEventFilterobligatoire
activebooleanobligatoire
statusWebhookStatusobligatoire
paused_atstring (date-time) | null
paused_reasonstring | null
failures : 10 tentatives échouées d’affilée ; feature_disabled : l’offre n’inclut pas les webhooks.
disabled_reasonstring | null
gone : le récepteur a répondu 410 ; manual : désactivé par un administrateur.
Valeurs autorisées: gonemanualnull
disabled_atstring (date-time) | null
roleWebhookRoleobligatoire
data_profile_idinteger | null
Profil de données du webhook (null signifie aucun profil, comme pour une clé API ayant le même rôle).
collection_idsarray of integerobligatoire
Collections dont le webhook reçoit les événements ; vide signifie toutes les collections accessibles au rôle et au profil de données.
tagsarray of stringobligatoire
Événements de fiches uniquement pour les fiches portant l’une de ces étiquettes ; vide signifie aucun filtre.
payloadWebhookPayloadModeobligatoire
headersarray of WebhookHeaderobligatoire
auth_typestring | null
Type d’autorisation sortante (null signifie aucune).
Valeurs autorisées: bearerbasicnull
auth_setbooleanobligatoire
Indique si une autorisation sortante est définie (les valeurs ne sont jamais renvoyées).
previous_secret_valid_untilstring (date-time) | null
Date jusqu’à laquelle les livraisons sont aussi signées avec l’ancien secret (null signifie qu’il n’y a pas de chevauchement).
healthWebhookHealth
consecutive_failuresintegerobligatoire
last_delivery_atstring (date-time) | null
last_success_atstring (date-time) | null
last_errorstring | null
created_byinteger | null
created_by_namestring | null
created_atstring (date-time)obligatoire
updated_atstring (date-time)obligatoire

400La requête est invalide : la valeur d’un paramètre ou l’état de l’objet ne permet pas l’action (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

Retry-After
Nombre de secondes à attendre avant de réessayer la requête.
RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← webhooks · Référence de l’API

curl -X PATCH 'https://api.sursa.com/v1/webhooks/1' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/sursa","description":"Customer support articles","events":["card.*"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Essayer

Clé API

La clé reste dans la mémoire de cet onglet et n’est envoyée qu’à https://api.sursa.com.

Les requêtes agissent sur les données réelles de votre organisation.

Idempotency-Key header

webhook_id path *

Idempotency-Key

Si ce champ est vide, une nouvelle clé est générée pour chaque requête.

Corps de la requête (JSON)