**Versions de l’API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=fr)

# Webhooks

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

Événements sortants — format fourni à titre de référence.

## Opérations

## GET /webhooks/catalog

Explain available event notifications in French

`get_owned_webhook_catalog`

Requires webhooks:manage and a fresh valid organisation key. Each subscription belongs to its exact organisation and creating key (OAuth refresh retains that key identity). Root/system principals and campaign-restricted keys are refused. Event subscriptions additionally require their resource read scope. Events carry references only; read business details through the independently authorised MCP/REST operations. Revocation or loss of event scopes stops managed delivery; an expired OAuth access token does not interrupt a still valid refresh grant. No wildcard, observed-state feeds, payment command or agent execution is enabled. Errors do not prove a mutation occurred; reconcile through list_owned_webhooks. Returns only subscriptions owned by this key; never another integration’s secret.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "webhooks:manage",
  "additional": []
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Qualified subscription result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookCatalogResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid subscription or unsupported event/URL.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Invalid or expired access token.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing scope, revoked authority, restricted or unsupported principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "No subscription belonging to this principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Request identity conflict or subscription limit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Unavailable or mutation not confirmed; reconcile before retry.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "webhooks:manage",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /webhooks/owned

List this integration’s own event subscriptions

`list_owned_webhooks`

Requires webhooks:manage and a fresh valid organisation key. Each subscription belongs to its exact organisation and creating key (OAuth refresh retains that key identity). Root/system principals and campaign-restricted keys are refused. Event subscriptions additionally require their resource read scope. Events carry references only; read business details through the independently authorised MCP/REST operations. Revocation or loss of event scopes stops managed delivery; an expired OAuth access token does not interrupt a still valid refresh grant. No wildcard, observed-state feeds, payment command or agent execution is enabled. Errors do not prove a mutation occurred; reconcile through list_owned_webhooks. Returns only subscriptions owned by this key; never another integration’s secret.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "webhooks:manage",
  "additional": []
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Qualified subscription result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookListResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid subscription or unsupported event/URL.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Invalid or expired access token.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing scope, revoked authority, restricted or unsupported principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "No subscription belonging to this principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Request identity conflict or subscription limit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Unavailable or mutation not confirmed; reconcile before retry.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "webhooks:manage",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PUT /webhooks/owned

Provision a private backend event subscription

`provision_owned_webhook`

Requires webhooks:manage and a fresh valid organisation key. Each subscription belongs to its exact organisation and creating key (OAuth refresh retains that key identity). Root/system principals and campaign-restricted keys are refused. Event subscriptions additionally require their resource read scope. Events carry references only; read business details through the independently authorised MCP/REST operations. Revocation or loss of event scopes stops managed delivery; an expired OAuth access token does not interrupt a still valid refresh grant. No wildcard, observed-state feeds, payment command or agent execution is enabled. Errors do not prove a mutation occurred; reconcile through list_owned_webhooks. Backend-only credential provisioning: choose a stable UUID request id and securely store the generated secret before sending; exact retries are idempotent, changed values conflict. The secret is never returned. Deliberately excluded from MCP because credentials must not pass through model arguments.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "webhooks:manage",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookPutRequest"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Qualified subscription result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookPutResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid subscription or unsupported event/URL.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Invalid or expired access token.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing scope, revoked authority, restricted or unsupported principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "No subscription belonging to this principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Request identity conflict or subscription limit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Unavailable or mutation not confirmed; reconcile before retry.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "webhooks:manage",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": false
}
```

## POST /webhooks/owned/{id}/disable

Stop one event subscription owned by this integration

`disable_owned_webhook`

Requires webhooks:manage and a fresh valid organisation key. Each subscription belongs to its exact organisation and creating key (OAuth refresh retains that key identity). Root/system principals and campaign-restricted keys are refused. Event subscriptions additionally require their resource read scope. Events carry references only; read business details through the independently authorised MCP/REST operations. Revocation or loss of event scopes stops managed delivery; an expired OAuth access token does not interrupt a still valid refresh grant. No wildcard, observed-state feeds, payment command or agent execution is enabled. Errors do not prove a mutation occurred; reconcile through list_owned_webhooks. Returns only subscriptions owned by this key; never another integration’s secret.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "webhooks:manage",
  "additional": []
}
```

### Paramètres

```json
{
  "in": "path",
  "name": "id",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookDisableRequest"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Qualified subscription result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookDisableResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid subscription or unsupported event/URL.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Invalid or expired access token.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing scope, revoked authority, restricted or unsupported principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "No subscription belonging to this principal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Request identity conflict or subscription limit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Unavailable or mutation not confirmed; reconcile before retry.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OwnedWebhookError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "webhooks:manage",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## Schémas

```json
{
  "components": {
    "schemas": {
      "OwnedWebhookCatalogResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "events": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OwnedWebhookEvent"
                }
              },
              "projection": {
                "type": "string",
                "enum": [
                  "references"
                ]
              }
            },
            "required": [
              "events",
              "projection"
            ]
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "OwnedWebhookEvent": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "label",
          "description"
        ]
      },
      "OwnedWebhookError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "OwnedWebhookListResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "subscriptions": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OwnedWebhookSubscription"
                }
              }
            },
            "required": [
              "subscriptions"
            ]
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "OwnedWebhookSubscription": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "active": {
            "type": "boolean"
          },
          "lastSuccessAt": {
            "type": "string",
            "nullable": true
          },
          "lastFailureAt": {
            "type": "string",
            "nullable": true
          },
          "projection": {
            "type": "string",
            "enum": [
              "references"
            ]
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "active",
          "lastSuccessAt",
          "lastFailureAt",
          "projection"
        ]
      },
      "OwnedWebhookPutRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "maxItems": 18,
            "uniqueItems": true,
            "items": {
              "type": "string"
            }
          },
          "secret": {
            "type": "string",
            "pattern": "^whsec_[a-f0-9]{64}$",
            "writeOnly": true
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "secret"
        ]
      },
      "OwnedWebhookPutResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "subscription": {
                "$ref": "#/components/schemas/OwnedWebhookSubscription"
              },
              "created": {
                "type": "boolean"
              }
            },
            "required": [
              "subscription",
              "created"
            ]
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "OwnedWebhookDisableRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "confirm": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "confirm"
        ]
      },
      "OwnedWebhookDisableResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "subscription": {
                "$ref": "#/components/schemas/OwnedWebhookSubscription"
              }
            },
            "required": [
              "subscription"
            ]
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
