# Webhook (/it/webhooks)



I webhook notificano al Suo server le modifiche nell'organizzazione Tapaya. Utilizzi la stessa integrazione per i pagamenti in presenza e online, indipendentemente dal processore di pagamento.

## Funzionamento [#how-it-works]

<WebhookLifecycle senderLabel="Tapaya" receiverLabel="Il Suo server" label="Una modifica confermata accoda un evento. Tapaya lo firma e lo invia. Il ricevitore lo verifica e lo memorizza. Una risposta 2xx conferma la consegna; in caso di errore, i tentativi riprendono dalla fase di invio, fino a 12 tentativi, poi si interrompono." event="Modifica salvata" queue="Evento in coda" send="POST firmata" receive="Verifica e memorizzazione" delivered="Consegnato" />

Configuri una destinazione HTTPS per organizzazione e selezioni gli eventi necessari. Tapaya invia una richiesta HTTP `POST` con un'istantanea JSON e una firma. Verifichi la firma, memorizzi l'evento e restituisca una risposta di esito positivo prima di elaborare la logica applicativa.

Può iscriversi a singoli tipi o a tutti i tipi supportati. Un'iscrizione a tutti i tipi riceve anche i nuovi tipi supportati in futuro, quindi ignori quelli che l'applicazione non riconosce.

## Integrazione rapida [#quick-integration]

<div className="fd-steps [&_h3]:fd-step">
  ### Salvare una destinazione [#save-a-destination]

  Nella Platform, apra **API Keys**, poi **Webhooks**. Inserisca l'URL HTTPS, scelga gli eventi necessari e salvi. Copi subito il signing secret (chiave di firma): viene mostrato una sola volta. Si veda [Configurazione](/webhooks/configuration).

  ### Verificare ogni richiesta [#verify-each-request]

  Calcoli un HMAC-SHA256 del timestamp, di un punto e del corpo originale con il Suo signing secret, e lo confronti con `X-Tapaya-Signature`. Si veda [Controllare la firma](/webhooks/receiving#check-the-signature).

  ### Memorizzare l'evento, poi restituire 2xx [#store-the-event-then-return-2xx]

  Salvi l'evento con un `id` univoco, risponda `2xx` entro 10 secondi e lo elabori in seguito. Si veda [Memorizzare e confermare](/webhooks/receiving#store-and-acknowledge).

  ### Inviare un webhook di test [#send-a-test-webhook]

  Nella stessa pagina, utilizzi l'azione di test per inviare un `webhook.test` firmato. Si veda [Inviare un webhook di test](/webhooks/receiving#send-a-test-webhook).
</div>

## Struttura comune dell'evento [#event-envelope]

Ogni evento utilizza questa struttura comune. L'istantanea della risorsa in `data` dipende dal tipo di evento.

```json
{
  "id": "019a0000-0000-7000-8000-000000000001",
  "type": "payment.succeeded",
  "apiVersion": "1",
  "organizationId": "019a0000-0000-7000-8000-000000000002",
  "merchantId": "019a0000-0000-7000-8000-000000000005",
  "createdAt": "2026-10-30T12:00:00.000000Z",
  "data": {
    "payment": {
      "id": "019a0000-0000-7000-8000-000000000003",
      "token": "example_payment_token",
      "merchantId": "019a0000-0000-7000-8000-000000000005",
      "status": "success",
      "statusId": 2,
      "requestedAmount": 10000,
      "requestedCurrencyId": 203,
      "settlementAmount": 10000,
      "settlementCurrencyId": 203
    }
  }
}
```

| Campo            | Significato                                                                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | ID univoco dell'evento. Lo utilizzi per deduplicare le consegne. I tentativi successivi mantengono lo stesso ID.                                         |
| `type`           | Nome dell'evento dal [catalogo degli eventi](/webhooks/events).                                                                                          |
| `apiVersion`     | Identificatore dello schema del payload, attualmente la stringa `"1"`.                                                                                   |
| `organizationId` | Organizzazione a cui appartiene l'evento. Verifichi che corrisponda alla Sua integrazione.                                                               |
| `merchantId`     | Esercente a cui appartiene la risorsa. Può essere `null` per pagamenti meno recenti la cui titolarità non è stata determinata o per un test diagnostico. |
| `createdAt`      | Ora UTC in cui è stato acquisito l'evento, anziché l'ora di consegna.                                                                                    |
| `data`           | Istantanea immutabile della risorsa al momento dell'acquisizione dell'evento.                                                                            |

Gli importi sono numeri interi espressi nell'unità minima della valuta del campo. Ad esempio, `10000` con l'ID numerico ISO 4217 della valuta `203` indica 100,00 CZK. Gli importi richiesti e di regolamento possono utilizzare valute diverse.

Ogni tipo di evento inserisce la propria istantanea in `data`. Per ogni struttura del payload e ogni valore di stato, si veda [Tipi di evento](/webhooks/events).

## Regole di consegna [#delivery-rules]

Tapaya invia un evento non appena la modifica viene salvata e continua a inviarlo finché il Suo server non risponde `2xx`.

| Regola          | Comportamento                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| Conferma        | Qualsiasi risposta `2xx` entro 10 secondi. I reindirizzamenti non vengono seguiti.                           |
| Nuovi tentativi | Fino a 12 tentativi in circa 20 ore, con attese di 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 e 360 minuti.       |
| Ordine          | Non garantito. La consegna avviene almeno una volta, quindi si aspetti duplicati e istantanee meno recenti.  |
| Concorrenza     | 2 richieste alla volta per organizzazione, condivise con i test manuali. Gli altri eventi attendono in coda. |

Una consegna fallita non cambia mai il pagamento stesso e le consegne passate non possono essere reinviate. Per recuperare dopo un'interruzione, legga lo stato corrente tramite le [API di pagamento e degli esercenti](/platform-api/reporting).

## Iniziare l'integrazione [#start-integrating]

<Cards>
  <Card title="Configurare una destinazione" href="/webhooks/configuration">
    Imposti l'URL, scelga gli eventi e salvi il signing secret (chiave di firma).
  </Card>

  <Card title="Consultare i tipi di evento" href="/webhooks/events">
    Trovi la condizione esatta che genera ogni evento di pagamento, esercente e onboarding.
  </Card>

  <Card title="Verificare e testare" href="/webhooks/receiving">
    Verifichi le firme e invii un webhook diagnostico.
  </Card>
</Cards>