# API : webhook-subscriptions

4 opérations REST du groupe webhook-subscriptions.

Base : `/api/v1`. [Conventions](/documentation/api-conventions/) · [Toutes les ressources](/documentation/api-reference/)

- GET /webhook-subscriptions : Lister les abonnements webhooks (jamais le secret)
- POST /webhook-subscriptions : Créer un abonnement - le secret whsec_ n'est montré qu'ici
- PATCH /webhook-subscriptions/{id} : Modifier un abonnement (url, événements, statut)
- DELETE /webhook-subscriptions/{id} : Supprimer un abonnement (ses livraisons partent avec lui)
## GET /webhook-subscriptions

```json
{
  "summary": "Lister les abonnements webhooks (jamais le secret)",
  "tags": [
    "Webhooks"
  ],
  "security": [
    {
      "oauth2": [
        "webhooks:manage"
      ]
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "200": {
      "description": "Tous les abonnements (liste complète, hors curseur)",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "url": {
                      "type": "string"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "company.created",
                          "company.updated",
                          "company.trashed",
                          "contact.created",
                          "contact.updated",
                          "contact.trashed",
                          "contact.anonymized",
                          "quote.created",
                          "quote.updated",
                          "quote.status_changed",
                          "quote.viewed",
                          "invoice.created",
                          "invoice.paid",
                          "invoice.late",
                          "invoice.issued",
                          "contract.created",
                          "contract.amended",
                          "contract.terminated",
                          "contract.expired",
                          "request.created",
                          "request.updated",
                          "request.status_changed",
                          "request.merged",
                          "request.due_soon",
                          "request.overdue",
                          "request.unassigned",
                          "sales_activity.created",
                          "sales_activity.completed",
                          "sales_activity.cancelled",
                          "invoice.einvoice.submitted",
                          "invoice.einvoice.status_changed",
                          "signature.viewed",
                          "signature.signed",
                          "signature.declined",
                          "signature.expired",
                          "signature.cancelled",
                          "signature.recipient.viewed",
                          "signature.recipient.signed",
                          "export.ready",
                          "campaign.sent",
                          "campaign.paused",
                          "contact.unsubscribed",
                          "contact.marketing_consent_changed",
                          "form.submitted",
                          "event.registered",
                          "event.attended",
                          "order.received",
                          "order.confirmed",
                          "order.delivered",
                          "order.cancelled",
                          "order.updated"
                        ]
                      }
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "consecutiveFailures": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "events",
                    "status",
                    "consecutiveFailures",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "data",
              "nextCursor"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```

## POST /webhook-subscriptions

```json
{
  "summary": "Créer un abonnement - le secret whsec_ n'est montré qu'ici",
  "description": "URL https obligatoire hors dev (garde SSRF, résolution DNS publique). Conservez `secret` immédiatement : il n'est jamais relisible ensuite.",
  "tags": [
    "Webhooks"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "maxLength": 2000,
              "format": "uri"
            },
            "events": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "company.created",
                  "company.updated",
                  "company.trashed",
                  "contact.created",
                  "contact.updated",
                  "contact.trashed",
                  "contact.anonymized",
                  "quote.created",
                  "quote.updated",
                  "quote.status_changed",
                  "quote.viewed",
                  "invoice.created",
                  "invoice.paid",
                  "invoice.late",
                  "invoice.issued",
                  "contract.created",
                  "contract.amended",
                  "contract.terminated",
                  "contract.expired",
                  "request.created",
                  "request.updated",
                  "request.status_changed",
                  "request.merged",
                  "request.due_soon",
                  "request.overdue",
                  "request.unassigned",
                  "sales_activity.created",
                  "sales_activity.completed",
                  "sales_activity.cancelled",
                  "invoice.einvoice.submitted",
                  "invoice.einvoice.status_changed",
                  "signature.viewed",
                  "signature.signed",
                  "signature.declined",
                  "signature.expired",
                  "signature.cancelled",
                  "signature.recipient.viewed",
                  "signature.recipient.signed",
                  "export.ready",
                  "campaign.sent",
                  "campaign.paused",
                  "contact.unsubscribed",
                  "contact.marketing_consent_changed",
                  "form.submitted",
                  "event.registered",
                  "event.attended",
                  "order.received",
                  "order.confirmed",
                  "order.delivered",
                  "order.cancelled",
                  "order.updated"
                ]
              }
            }
          },
          "required": [
            "url",
            "events"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "webhooks:manage"
      ]
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "201": {
      "description": "Abonnement créé, secret inclus",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "url": {
                "type": "string"
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "company.created",
                    "company.updated",
                    "company.trashed",
                    "contact.created",
                    "contact.updated",
                    "contact.trashed",
                    "contact.anonymized",
                    "quote.created",
                    "quote.updated",
                    "quote.status_changed",
                    "quote.viewed",
                    "invoice.created",
                    "invoice.paid",
                    "invoice.late",
                    "invoice.issued",
                    "contract.created",
                    "contract.amended",
                    "contract.terminated",
                    "contract.expired",
                    "request.created",
                    "request.updated",
                    "request.status_changed",
                    "request.merged",
                    "request.due_soon",
                    "request.overdue",
                    "request.unassigned",
                    "sales_activity.created",
                    "sales_activity.completed",
                    "sales_activity.cancelled",
                    "invoice.einvoice.submitted",
                    "invoice.einvoice.status_changed",
                    "signature.viewed",
                    "signature.signed",
                    "signature.declined",
                    "signature.expired",
                    "signature.cancelled",
                    "signature.recipient.viewed",
                    "signature.recipient.signed",
                    "export.ready",
                    "campaign.sent",
                    "campaign.paused",
                    "contact.unsubscribed",
                    "contact.marketing_consent_changed",
                    "form.submitted",
                    "event.registered",
                    "event.attended",
                    "order.received",
                    "order.confirmed",
                    "order.delivered",
                    "order.cancelled",
                    "order.updated"
                  ]
                }
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "disabled"
                ]
              },
              "consecutiveFailures": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              },
              "secret": {
                "type": "string",
                "description": "Secret de signature whsec_ - montré UNIQUEMENT dans cette réponse, jamais relisible"
              }
            },
            "required": [
              "id",
              "url",
              "events",
              "status",
              "consecutiveFailures",
              "createdAt",
              "updatedAt",
              "secret"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```

## PATCH /webhook-subscriptions/{id}

```json
{
  "summary": "Modifier un abonnement (url, événements, statut)",
  "description": "Repasser `status` à `active` réarme le compteur d'échecs consécutifs (même sémantique que la réactivation UI).",
  "tags": [
    "Webhooks"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "maxLength": 2000,
              "format": "uri"
            },
            "events": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "company.created",
                  "company.updated",
                  "company.trashed",
                  "contact.created",
                  "contact.updated",
                  "contact.trashed",
                  "contact.anonymized",
                  "quote.created",
                  "quote.updated",
                  "quote.status_changed",
                  "quote.viewed",
                  "invoice.created",
                  "invoice.paid",
                  "invoice.late",
                  "invoice.issued",
                  "contract.created",
                  "contract.amended",
                  "contract.terminated",
                  "contract.expired",
                  "request.created",
                  "request.updated",
                  "request.status_changed",
                  "request.merged",
                  "request.due_soon",
                  "request.overdue",
                  "request.unassigned",
                  "sales_activity.created",
                  "sales_activity.completed",
                  "sales_activity.cancelled",
                  "invoice.einvoice.submitted",
                  "invoice.einvoice.status_changed",
                  "signature.viewed",
                  "signature.signed",
                  "signature.declined",
                  "signature.expired",
                  "signature.cancelled",
                  "signature.recipient.viewed",
                  "signature.recipient.signed",
                  "export.ready",
                  "campaign.sent",
                  "campaign.paused",
                  "contact.unsubscribed",
                  "contact.marketing_consent_changed",
                  "form.submitted",
                  "event.registered",
                  "event.attended",
                  "order.received",
                  "order.confirmed",
                  "order.delivered",
                  "order.cancelled",
                  "order.updated"
                ]
              }
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "disabled"
              ]
            }
          },
          "additionalProperties": false
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "webhooks:manage"
      ]
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "200": {
      "description": "Abonnement modifié",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "url": {
                "type": "string"
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "company.created",
                    "company.updated",
                    "company.trashed",
                    "contact.created",
                    "contact.updated",
                    "contact.trashed",
                    "contact.anonymized",
                    "quote.created",
                    "quote.updated",
                    "quote.status_changed",
                    "quote.viewed",
                    "invoice.created",
                    "invoice.paid",
                    "invoice.late",
                    "invoice.issued",
                    "contract.created",
                    "contract.amended",
                    "contract.terminated",
                    "contract.expired",
                    "request.created",
                    "request.updated",
                    "request.status_changed",
                    "request.merged",
                    "request.due_soon",
                    "request.overdue",
                    "request.unassigned",
                    "sales_activity.created",
                    "sales_activity.completed",
                    "sales_activity.cancelled",
                    "invoice.einvoice.submitted",
                    "invoice.einvoice.status_changed",
                    "signature.viewed",
                    "signature.signed",
                    "signature.declined",
                    "signature.expired",
                    "signature.cancelled",
                    "signature.recipient.viewed",
                    "signature.recipient.signed",
                    "export.ready",
                    "campaign.sent",
                    "campaign.paused",
                    "contact.unsubscribed",
                    "contact.marketing_consent_changed",
                    "form.submitted",
                    "event.registered",
                    "event.attended",
                    "order.received",
                    "order.confirmed",
                    "order.delivered",
                    "order.cancelled",
                    "order.updated"
                  ]
                }
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "disabled"
                ]
              },
              "consecutiveFailures": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              }
            },
            "required": [
              "id",
              "url",
              "events",
              "status",
              "consecutiveFailures",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```

## DELETE /webhook-subscriptions/{id}

```json
{
  "summary": "Supprimer un abonnement (ses livraisons partent avec lui)",
  "tags": [
    "Webhooks"
  ],
  "security": [
    {
      "oauth2": [
        "webhooks:manage"
      ]
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "200": {
      "description": "Abonnement supprimé",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "deleted": {
                "type": "boolean",
                "const": true
              }
            },
            "required": [
              "id",
              "deleted"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```