# Configurazione (/it/webhooks/configuration)





Ogni organizzazione dispone di una destinazione webhook e di un signing secret (chiave di firma) attivo. Lo configuri nella Platform o dal Suo server.

| Dettaglio       | Valore                                                                                          |
| --------------- | ----------------------------------------------------------------------------------------------- |
| URL di base     | `https://api.sandbox.tapaya.com` per la sandbox, `https://api.tapaya.com` per la produzione     |
| Autenticazione  | Server Secret Token in `Authorization`. Si veda [Autenticazione](/platform-api#authentication). |
| Ambito          | Una destinazione per organizzazione                                                             |
| Guida correlata | [Verificare e testare](/webhooks/receiving)                                                     |

## Configurare nella Platform [#configure-in-the-platform]

Apra [API Keys](https://platform.tapaya.com/api-keys/) per la Sua organizzazione e individui **Webhooks**.

1. Inserisca il Suo URL HTTPS pubblico.
2. Scelga gli eventi di cui ha bisogno oppure attivi **Subscribe to all webhook types**.
3. Attivi **Enable** e faccia clic su **Save**.
4. Copi il signing secret e lo conservi sul Suo server.
5. Invii un [webhook di test](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="Il signing secret viene mostrato una sola volta">
  Lo copi quando crea o ruota la destinazione; non potrà recuperarlo in seguito. Serve solo a verificare i webhook in arrivo. Il Server Secret Token autorizza le richieste di configurazione.
</Callout>

## Tutte le operazioni [#all-operations]

| Operazione                                          | Serve a                                                                          |
| --------------------------------------------------- | -------------------------------------------------------------------------------- |
| [Salvare una destinazione](#save-a-destination)     | Creare o sostituire l'iscrizione corrente oppure ruotarne il signing secret.     |
| [Leggere una destinazione](#read-a-destination)     | Recuperare l'URL corrente, la modalità di iscrizione e lo stato di abilitazione. |
| [Eliminare una destinazione](#delete-a-destination) | Rimuovere l'iscrizione, la coda di consegna e la cronologia.                     |

## Gestire la destinazione [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Salvare una destinazione" id="save-a-destination">
    **Serve a** collegare il ricevitore HTTPS e scegliere gli eventi da consegnare.

    ```bash
    curl --request PUT \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME' \
      --header 'Content-Type: application/json' \
      --data '{
        "url": "https://payments.example.com/webhooks/tapaya",
        "eventTypes": ["payment.succeeded", "payment.failed", "payment.refund.succeeded"],
        "subscribeAllEventTypes": false,
        "enabled": true,
        "rotateSecret": false
      }'
    ```

    **Da sapere:**

    * Questa operazione sostituisce la configurazione salvata; non aggiunge un secondo endpoint.
    * La creazione e la rotazione esplicita restituiscono `{"signingSecret":"twhsec_..."}`. Un aggiornamento ordinario restituisce `{"signingSecret":null}`.
    * Salvi il segreto restituito per intero, incluso il prefisso. Non viene mai restituito da GET.
    * È il Suo token a determinare l'organizzazione; non invii un ID organizzazione.

    **Parametri:**

    | Campo                    | Obbligatorio | Significato                                                                                                                  |
    | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
    | `url`                    | Sì           | URL HTTPS pubblico sulla porta 443, fino a 2.048 caratteri, senza credenziali incorporate né frammento.                      |
    | `eventTypes`             | Sì           | Array di nomi del [catalogo](/webhooks/events). Ne scelga almeno uno, a meno che non si iscriva a tutti i tipi.              |
    | `subscribeAllEventTypes` | No           | Il valore predefinito è `false`. Imposti `true` con `eventTypes: []` per includere tutti i tipi supportati attuali e futuri. |
    | `enabled`                | Sì           | Quando è `true`, acquisisce i nuovi eventi corrispondenti e invia quelli in coda.                                            |
    | `rotateSecret`           | Sì           | Quando è `true`, genera e restituisce un nuovo signing secret.                                                               |
  </Accordion>

  <Accordion title="Leggere una destinazione" id="read-a-destination">
    **Serve a** esaminare l'iscrizione salvata senza rivelarne il signing secret.

    ```bash
    curl 'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Da sapere:**

    * GET restituisce `404` quando l'organizzazione non ha una destinazione.
    * Le iscrizioni a tutti i tipi restituiscono un array `eventTypes` vuoto con `subscribeAllEventTypes: true`.
    * La risposta non include mai il signing secret.
    * Utilizzi `availableEventTypes` per creare un selettore di eventi senza scrivere il catalogo direttamente nel codice.

    **Restituisce:**

    | Campo                    | Significato                                                                |
    | ------------------------ | -------------------------------------------------------------------------- |
    | `url`                    | Destinazione HTTPS salvata.                                                |
    | `eventTypes`             | Iscrizioni esplicite oppure un array vuoto nella modalità di tutti i tipi. |
    | `subscribeAllEventTypes` | Indica se sono selezionati i tipi supportati attuali e futuri.             |
    | `enabled`                | Indica se i webhook sono abilitati.                                        |
    | `availableEventTypes`    | Tutti i nomi di evento a cui può iscriversi.                               |
  </Accordion>

  <Accordion title="Eliminare una destinazione" id="delete-a-destination">
    **Serve a** scollegare l'organizzazione e rimuovere le consegne in coda e la cronologia delle consegne.

    ```bash
    curl --request DELETE \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Da sapere:**

    * In caso di successo viene restituito HTTP `204` senza corpo della risposta.
    * Una richiesta già in corso può comunque arrivare dopo l'eliminazione.
    * Ricreare la destinazione genera un nuovo signing secret e non ripristina gli eventi eliminati.
  </Accordion>
</Accordions>

## Regole della destinazione [#configuration]

### Modificare le impostazioni [#configuration-changes]

| Quando                                  | Cosa succede                                                                                                                                                                                             |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Modifica l'URL, gli eventi o il segreto | I nuovi eventi usano le nuove impostazioni. Gli eventi in coda mantengono l'URL e il segreto precedenti, quindi li mantenga entrambi funzionanti finché la coda non si svuota.                           |
| Disabilita i webhook                    | Le consegne in coda vengono sospese e non vengono acquisiti nuovi eventi. La riabilitazione riprende la coda, ma le modifiche perse non vengono recuperate retroattivamente. I test funzionano comunque. |
| Elimina la destinazione                 | Gli eventi in coda e la cronologia delle consegne vengono rimossi. Una richiesta già in corso può comunque arrivare. Ricreare la destinazione genera un nuovo signing secret.                            |

### Requisiti dell'URL [#destination-requirements]

* HTTPS pubblico sulla porta 443. Localhost e reti private vengono rifiutati, e il DNS viene controllato nuovamente a ogni connessione.
* Nessuna credenziale incorporata, nessun frammento e nessun reindirizzamento.
* Nessun header di autorizzazione personalizzato. Verifichi invece la firma Tapaya, oppure inserisca un adattatore lato server davanti a un URL che richiede una propria chiave.

## Errori [#errors]

Le richieste di configurazione falliscono con queste risposte. Un ricevitore che rifiuta o non riceve una consegna è un problema diverso; si veda [Gestire gli errori](/webhooks/receiving#handle-errors).

| Risposta     | Significato                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `400` su PUT | URL non valido, tipo di evento non supportato, campo obbligatorio mancante oppure selezione esplicita degli eventi vuota. |
| `401`        | Il Server Secret Token è mancante o non valido.                                                                           |
| `404` su GET | Non esiste una destinazione per l'organizzazione autenticata.                                                             |

Prosegua con la [verifica della firma e la consegna di test](/webhooks/receiving).