Webhook di Applicazione

I webhook di applicazione sono chiamate HTTP che Riseact invia al tuo endpoint quando si verificano determinati eventi in tutte le organizzazioni che hanno installato la tua applicazione.

A differenza dei webhook di organizzazione, si registrano una sola volta sulla tua partner app: non devi configurarli per ogni organizzazione. Ogni chiamata include il dominio dell'organizzazione che ha generato l'evento, così puoi capire a chi si riferisce.

Impostare un webhook

I webhook di applicazione si gestiscono dal portale partner Riseact, nella pagina di dettaglio dell'app.

1. Apri il portale partner e vai su Apps.
2. Seleziona la tua applicazione.
3. Apri la scheda Webhooks.
4. Clicca Add Webhook.
5. Seleziona gli eventi che vuoi ricevere (vedi Eventi disponibili) e inserisci l'URL HTTPS del tuo endpoint, quello che riceverà le chiamate POST.
6. Salva.

Ogni webhook registrato compare nella scheda con gli eventi sottoscritti e l'URL. Da lì puoi modificarlo o eliminarlo in qualsiasi momento.

Eventi disponibili

Evento	Descrizione
supporter.created	Un nuovo sostenitore è stato creato
supporter.updated	Un sostenitore è stato aggiornato
supporter.deleted	Un sostenitore è stato eliminato
checkout.created	Un nuovo checkout è stato aperto
checkout.updated	Un checkout è stato aggiornato
checkout.paid	Un checkout è stato completato con pagamento
checkout.closed	Un checkout è stato chiuso
donation.created	Una nuova donazione è stata creata
donation.updated	Una donazione è stata aggiornata
donation.deleted	Una donazione è stata eliminata
payment.created	Un nuovo pagamento è stato registrato
payment.updated	Un pagamento è stato aggiornato
campaign.created	Una nuova campagna è stata creata
campaign.updated	Una campagna è stata aggiornata
campaign.deleted	Una campagna è stata eliminata

Consegna delle chiamate

Riseact invia una richiesta POST con Content-Type: application/json all'URL registrato. Il payload è identico a quello dei webhook di organizzazione e contiene:

• organization — il dominio dell'organizzazione che ha generato l'evento. È il campo chiave per instradare l'evento: la tua app riceve eventi da tutte le organizzazioni installate, quindi usalo per capire di quale si tratta.
• event — il topic dell'evento (es. donation.created).
• object — l'oggetto interessato dall'evento.
• idempotency_key — identificativo univoco della chiamata. La stessa chiave può arrivare più volte: gestiscila in modo idempotente per deduplicare.

Esempio (donation.created):

{
  "organization": "org-che-ha-installato-app",
  "object": {
    "id": 229,
    "code": "#1000",
    "state": "pending",
    "amount": 10,
    "frequency": 0,
    "campaign": 29,
    "supporter": 75835,
    "payment_method": "MANUAL"
  },
  "event": "donation.created",
  "idempotency_key": "b1e0c9a2-4f3d-4e2a-9c1b-6a7f8d0e2c34"
}

Per gli altri tipi di oggetto (sostenitore, checkout, pagamento) vedi gli esempi completi sulla pagina dei webhook di organizzazione.

Note operative:

• Il timeout della richiesta è di 10 secondi. Rispondi subito con 2xx ed elabora il payload in modo asincrono se il lavoro è pesante.
• Non è previsto un meccanismo di firma (HMAC/secret). Se ti serve verificare la provenienza, usa un URL con un percorso segreto o un token in query string, e valida idempotency_key.

Registro degli eventi

Il portale partner registra ogni tentativo di consegna. Nella scheda Events della tua app trovi l'elenco delle chiamate inviate, con per ciascuna:

• l'organizzazione di riferimento;
• l'evento e il payload inviato;
• lo stato HTTP della risposta (o l'eventuale errore di connessione);
• il corpo della risposta del tuo endpoint.

Se una consegna fallisce (endpoint irraggiungibile, risposta di errore) puoi rilanciarla manualmente dal dettaglio dell'evento. Usa questa schermata per diagnosticare i problemi di integrazione.

Differenza rispetto ai webhook di organizzazione

	Webhook di applicazione	Webhook di organizzazione
Ambito	Tutte le org che installano l'app	Una sola organizzazione
Dove si registrano	Portale partner, scheda Webhooks	Admin dell'organizzazione, app privata
Chi li usa	Partner app di terze parti	Automazioni e integrazioni interne
Payload	Uguale (include organization)	Uguale (include organization)