# Webhooks

## GET `/webhooks`

**Lister les endpoints de webhooks**

Admin de l’espace. Vingt endpoints au plus : la liste tient en une page.

Demande une clé d’API avec la portée `portal:read`.

### Paramètres de requête

| Champ    | Type    | Obligatoire | Description                          |
| -------- | ------- | ----------- | ------------------------------------ |
| `limit`  | integer | Non         | Par défaut : `20`. min. 1, max. 100. |
| `cursor` | string  | Non         |                                      |

### Réponses

| Code  | Description              | Corps     |
| ----- | ------------------------ | --------- |
| `200` | Succès                   | `objet`   |
| `400` | Requête invalide         | `Problem` |
| `401` | Authentification requise | `Problem` |
| `403` | Accès refusé             | `Problem` |
| `429` | Trop de requêtes         | `Problem` |
| `500` | Erreur interne           | `Problem` |

### Champs de la réponse `200`

| Champ                 | Type                                                                                                                                                                        | Description                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `data`                | objet\[]                                                                                                                                                                    |                                               |
| `data[].id`           | string                                                                                                                                                                      | Identifiant Portal.                           |
| `data[].object`       | string                                                                                                                                                                      |                                               |
| `data[].url`          | string                                                                                                                                                                      |                                               |
| `data[].description`  | string ou null                                                                                                                                                              |                                               |
| `data[].events`       | “invoice.issued” \| “invoice.paid” \| “signature.completed” \| “request.created” \| “action.submitted” \| “meeting.scheduled” \| “prospect.created” \| “project.created”\[] |                                               |
| `data[].enabled`      | boolean                                                                                                                                                                     |                                               |
| `data[].secret_last4` | string                                                                                                                                                                      |                                               |
| `next_cursor`         | string ou null                                                                                                                                                              | À renvoyer en `cursor` pour la page suivante. |
| `has_more`            | boolean                                                                                                                                                                     |                                               |

### Exemple

```bash
curl -X GET "https://app.hgdc.ch/portal/api/v1/webhooks" \
  -H "Authorization: Bearer $HGDC_PORTAL_API_KEY"
```

Réponse `200` :

```json
{
  "data": [
    {
      "id": "exemple",
      "object": "exemple",
      "url": "exemple",
      "description": "exemple",
      "events": [
        "invoice.issued"
      ],
      "enabled": true,
      "secret_last4": "exemple"
    }
  ],
  "next_cursor": "exemple",
  "has_more": true
}
```

## POST `/webhooks`

**Ajouter un endpoint de webhooks**

Admin de l’espace. Les événements sont signés au format Standard Webhooks ; le secret n’est rendu qu’ici, une fois.

Demande une clé d’API avec la portée `portal:write`.

### Corps de la requête

Type de contenu : `application/json`.

| Champ         | Type                                                                                                                                                                        | Obligatoire | Description                                                                |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- |
| `url`         | string (uri)                                                                                                                                                                | Oui         | Adresse HTTPS publique qui reçoit les événements. 2000 caractères au plus. |
| `description` | string                                                                                                                                                                      | Non         | 120 caractères au plus.                                                    |
| `events`      | “invoice.issued” \| “invoice.paid” \| “signature.completed” \| “request.created” \| “action.submitted” \| “meeting.scheduled” \| “prospect.created” \| “project.created”\[] | Oui         |                                                                            |

### Réponses

| Code  | Description                          | Corps     |
| ----- | ------------------------------------ | --------- |
| `201` | Succès                               | `objet`   |
| `400` | Requête invalide                     | `Problem` |
| `401` | Authentification requise             | `Problem` |
| `403` | Accès refusé                         | `Problem` |
| `415` | Format de requête non pris en charge | `Problem` |
| `422` | Paramètres invalides                 | `Problem` |
| `429` | Trop de requêtes                     | `Problem` |
| `500` | Erreur interne                       | `Problem` |

### Champs de la réponse `201`

| Champ          | Type                                                                                                                                                                        | Description                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `id`           | string                                                                                                                                                                      | Identifiant Portal.                                             |
| `object`       | string                                                                                                                                                                      |                                                                 |
| `url`          | string                                                                                                                                                                      |                                                                 |
| `description`  | string ou null                                                                                                                                                              |                                                                 |
| `events`       | “invoice.issued” \| “invoice.paid” \| “signature.completed” \| “request.created” \| “action.submitted” \| “meeting.scheduled” \| “prospect.created” \| “project.created”\[] |                                                                 |
| `enabled`      | boolean                                                                                                                                                                     |                                                                 |
| `secret_last4` | string                                                                                                                                                                      |                                                                 |
| `secret`       | string                                                                                                                                                                      | Secret de signature (Standard Webhooks), montré une seule fois. |

### Exemple

```bash
curl -X POST "https://app.hgdc.ch/portal/api/v1/webhooks" \
  -H "Authorization: Bearer $HGDC_PORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemple.ch","events":["invoice.issued"]}'
```

Réponse `201` :

```json
{
  "id": "exemple",
  "object": "exemple",
  "url": "exemple",
  "description": "exemple",
  "events": [
    "invoice.issued"
  ],
  "enabled": true,
  "secret_last4": "exemple",
  "secret": "exemple"
}
```

## DELETE `/webhooks/{id}`

**Supprimer un endpoint de webhooks**

Demande une clé d’API avec la portée `portal:write`.

### Paramètres de chemin

| Champ | Type   | Obligatoire | Description |
| ----- | ------ | ----------- | ----------- |
| `id`  | string | Oui         |             |

### Réponses

| Code  | Description              | Corps     |
| ----- | ------------------------ | --------- |
| `204` | Succès                   |           |
| `400` | Requête invalide         | `Problem` |
| `401` | Authentification requise | `Problem` |
| `403` | Accès refusé             | `Problem` |
| `404` | Ressource introuvable    | `Problem` |
| `429` | Trop de requêtes         | `Problem` |
| `500` | Erreur interne           | `Problem` |

### Exemple

```bash
curl -X DELETE "https://app.hgdc.ch/portal/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer $HGDC_PORTAL_API_KEY"
```