> ## 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.

# Schedulazione e webhook in ingresso

> Workflow cron-scheduled e ricezione di eventi da sistemi esterni.

Due modalità di avvio: **schedulazione** (periodica) e **webhook in ingresso** (da sistemi esterni).

## Workflow schedulati

### Cron expression

Arya supporta sintassi cron standard:

```
minuto ora giorno mese giorno-settimana

0 9 * * 1      → Ogni lunedì alle 9:00
0 */4 * * *    → Ogni 4 ore
30 18 * * 1-5  → Feriali alle 18:30
0 0 1 * *      → Primo del mese a mezzanotte
```

### Scope

Uno scheduled workflow può operare su:

* **Il workspace** (1 esecuzione per trigger, es. "invia report settimanale team")
* **Un insieme di record** (1 esecuzione per record, es. "per ogni fattura aperta da >30gg invia sollecito")

<Steps>
  <Step title="Configura">
    Trigger tipo **Scheduled** → cron expression + timezone + scope.
  </Step>

  <Step title="Test">
    Click **Esegui ora** per testare senza aspettare il prossimo slot.
  </Step>

  <Step title="Attiva">
    Switch Attivo. Il workflow si esegue automaticamente.
  </Step>
</Steps>

### Esempi pratici

<AccordionGroup>
  <Accordion title="Report settimanale">
    Ogni lunedì 9:00 → query pipeline deal → genera grafico → email a manager.
  </Accordion>

  <Accordion title="Cleanup duplicati">
    Ogni domenica notte → trova contatti duplicati → notifica HR per merge.
  </Accordion>

  <Accordion title="Compleanni clienti">
    Ogni giorno 8:00 → cerca contatti con compleanno oggi → invia email auguri personalizzata.
  </Accordion>

  <Accordion title="Solleciti fatture">
    Ogni giorno → fatture scadute da 7/30/60gg → email sollecito di livello crescente.
  </Accordion>

  <Accordion title="Expiry check">
    Ogni settimana → certificazioni in scadenza entro 30gg → task a HR + email al dipendente.
  </Accordion>
</AccordionGroup>

## Webhook in ingresso

Permettono a sistemi esterni di avviare workflow Arya chiamando un URL HTTP.

### Configurazione

<Steps>
  <Step title="Crea trigger webhook">
    Trigger tipo **Webhook in ingresso** → Arya genera URL univoco:

    ```
    https://api.arya.so/webhooks/wh_abc123xyz
    ```
  </Step>

  <Step title="Imposta autenticazione">
    * **None**: chiunque con URL può triggerare (sconsigliato)
    * **Token**: header `X-Webhook-Token: xxx`
    * **HMAC**: firma del body con chiave segreta (più sicuro)
  </Step>

  <Step title="Definisci schema payload">
    Specifica la struttura JSON attesa. Arya valida ogni chiamata.

    ```json theme={null}
    {
      "contact": {
        "first_name": "string",
        "last_name": "string",
        "email": "string"
      },
      "source": "string"
    }
    ```
  </Step>

  <Step title="Test">
    Invia una chiamata di test (Arya fornisce esempio cURL).

    ```bash theme={null}
    curl -X POST https://api.arya.so/webhooks/wh_abc123xyz \
      -H "X-Webhook-Token: xxx" \
      -H "Content-Type: application/json" \
      -d '{"contact": {"first_name": "Mario", ...}}'
    ```
  </Step>

  <Step title="Attiva e condividi URL">
    Passa URL + schema al sistema che deve chiamare (Zapier, Make, partner, sistema interno).
  </Step>
</Steps>

### Use case webhook

<AccordionGroup>
  <Accordion title="Form Typeform → crea lead Arya">
    Typeform invia submission → webhook Arya → crea contatto + aggiunge a lista.
  </Accordion>

  <Accordion title="Zapier/Make orchestration">
    Zapier connette N sistemi → triggera Arya come endpoint di uno step.
  </Accordion>

  <Accordion title="Sistema ERP interno">
    ERP nota nuovo ordine → chiama Arya → crea deal + aggiorna fattura.
  </Accordion>

  <Accordion title="Outreach tools (HeyReach, Instantly)">
    Tool esterni di outreach chiamano Arya al rispondere di un lead → crea record + assegna a rep.
  </Accordion>
</AccordionGroup>

### Gestione errori

Se il workflow fallisce, Arya risponde al webhook con:

* `200 OK` + body con errore se vuoi che il sistema esterno lo veda
* `500 Error` se vuoi che Zapier/Make ritentino

Configurabile da **Avanzate → Error response**.

### Logging

Ogni chiamata webhook è loggata in **Cronologia webhook**:

* Timestamp
* IP sorgente
* Payload ricevuto
* Risposta inviata
* Workflow innescato (se è scattato)

## Differenza con webhook esposti

* **Webhook in ingresso** (questa pagina): Arya riceve dall'esterno
* [**Webhook esposti**](/it/automazioni/webhook-esposti): Arya notifica l'esterno (outbound)

## Domande frequenti

<AccordionGroup>
  <Accordion title="Posso mettere in pausa un workflow schedulato senza eliminarlo?">Sì, switch Attivo/Pausato. Riprende dal prossimo slot al riattivarlo.</Accordion>
  <Accordion title="L'URL webhook è segreto?">Solo se autenti (token/HMAC). Senza autenticazione, è pubblico in rete e chiunque può triggerare.</Accordion>
  <Accordion title="Quanti webhook posso ricevere al secondo?">Rate limit 100 req/sec per workspace, 500 req/sec per piani Enterprise. Oltre il limite Arya risponde 429 con header `Retry-After`.</Accordion>
</AccordionGroup>