> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arya.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook esposti

> Arya notifica sistemi esterni via HTTP quando succedono eventi.

I **webhook esposti** permettono ad Arya di notificare sistemi esterni via HTTP quando succedono eventi nel workspace. Il contrario dei webhook in ingresso.

<Frame>
  <img src="https://mintcdn.com/agevole/BUuJGD62nuns4mJL/images/automazioni/it/outbound-webhooks.svg?fit=max&auto=format&n=BUuJGD62nuns4mJL&q=85&s=ff898fb749cc8e2dc1f447a445d76b3f" alt="Diagramma Arya → HTTP POST → sistema esterno" width="1200" height="720" data-path="images/automazioni/it/outbound-webhooks.svg" />
</Frame>

## Use case tipici

* **ETL**: ogni modifica di un record viene replicata in un data warehouse esterno
* **Analytics**: eventi Arya mandati a Segment, Mixpanel, Amplitude
* **ERP legacy**: notifica al sistema contabile quando una fattura è emessa
* **Sistema interno custom**: dashboard in tempo reale che consuma gli eventi Arya

## Configurazione

### Via workflow

Usi un normale workflow con azione **HTTP Request**:

<Steps>
  <Step title="Crea workflow">
    Trigger: evento che vuoi notificare (record creato/aggiornato, stato cambiato).
  </Step>

  <Step title="Azione HTTP Request">
    * **URL**: endpoint del sistema esterno
    * **Metodo**: POST (tipico)
    * **Headers**: auth, content-type
    * **Body**: JSON con dati del record
  </Step>

  <Step title="Gestisci errori">
    Retry logic, fallback, notifica admin se fallisce ripetutamente.
  </Step>
</Steps>

### Webhook esposti preconfigurati

Per use case comuni, Arya offre webhook pre-fatti da attivare con un click:

<AccordionGroup>
  <Accordion title="Deal events">
    `deal.created`, `deal.updated`, `deal.stage_changed`, `deal.won`, `deal.lost`.
    Payload: dati completi del deal + before/after dei campi modificati.
  </Accordion>

  <Accordion title="Invoice events">
    `invoice.issued`, `invoice.paid`, `invoice.overdue`.
  </Accordion>

  <Accordion title="Employee events">
    `employee.hired`, `employee.terminated`, `leave.approved`.
  </Accordion>

  <Accordion title="Quote events">
    `quote.sent`, `quote.viewed`, `quote.signed`, `quote.rejected`.
  </Accordion>

  <Accordion title="Task events">
    `task.assigned`, `task.completed`, `task.overdue`.
  </Accordion>
</AccordionGroup>

Attivi da **Impostazioni → Webhook esposti → + Nuovo**.

## Payload standard

Esempio payload `deal.won`:

```json theme={null}
{
  "event": "deal.won",
  "timestamp": "2026-04-14T15:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "deal": {
      "id": "deal_xyz",
      "name": "Rinnovo Acme 2026",
      "value": 25000,
      "currency": "EUR",
      "stage": "Won",
      "closed_at": "2026-04-14T15:30:00Z",
      "owner": {
        "id": "user_def",
        "name": "Mario Rossi",
        "email": "mario@arya.so"
      },
      "company": {
        "id": "comp_ghi",
        "name": "Acme SpA",
        "vat": "IT12345678901"
      }
    }
  },
  "signature": "hmac-sha256-hash-of-body"
}
```

## Sicurezza

<AccordionGroup>
  <Accordion title="HMAC signature">
    Arya firma il body con chiave segreta condivisa. Il sistema ricevente verifica la firma per garantire autenticità.
  </Accordion>

  <Accordion title="IP whitelist">
    Se il sistema esterno ha IP fissi, puoi whitelisting a livello di network.
  </Accordion>

  <Accordion title="HTTPS obbligatorio">
    Arya rifiuta URL HTTP non cifrati.
  </Accordion>

  <Accordion title="Timeout">
    Default 10 secondi. Se il sistema esterno non risponde, Arya considera fallito e ritenta.
  </Accordion>
</AccordionGroup>

## Retry e idempotenza

<Warning>
  Arya ritenta automaticamente su failure (503, timeout, errori di rete) con backoff esponenziale (1, 2, 4, 8 min). Dopo 5 tentativi marca come fallito e notifica admin.

  Il tuo endpoint deve essere **idempotente**: potresti ricevere la stessa notifica più volte. Usa l'event ID per deduplicare.
</Warning>

## Monitoraggio

In **Impostazioni → Webhook esposti → Log** vedi per ogni webhook:

* Timestamp
* URL chiamato
* Payload inviato
* Risposta ricevuta
* Status (success, failed)
* Numero tentativi

Puoi **ritentare manualmente** un webhook fallito.

## Domande frequenti

<AccordionGroup>
  <Accordion title="Il payload include dati sensibili?">
    Dipende dai campi. Per evitare di inviare dati confidenziali (es. stipendi, codici fiscali), configura filtri sui campi inclusi nel payload.
  </Accordion>

  <Accordion title="Posso avere webhook diversi per eventi diversi?">
    Sì, ogni webhook ha il suo URL + eventi sottoscritti.
  </Accordion>

  <Accordion title="Che succede se disabilito un workflow che manda webhook?">
    Si ferma. I webhook già in coda vengono comunque consegnati prima dello stop.
  </Accordion>
</AccordionGroup>