Webhook di Organizzazione

I webhook di organizzazione sono chiamate HTTP che Riseact invia al tuo endpoint quando si verificano determinati eventi all'interno di una singola organizzazione (creazione di un sostenitore, pagamento di un checkout, ecc.).

Sono legati a una sola organizzazione: si registrano con il token di un'applicazione privata e ricevono solo gli eventi di quella organizzazione. Se stai sviluppando una partner app che deve ricevere eventi da tutte le organizzazioni che l'hanno installata, usa invece i webhook di applicazione.

Impostare un webhook

I webhook di organizzazione si gestiscono dal pannello di amministrazione, nella pagina di dettaglio di un'applicazione privata. Non è richiesto alcun permesso oltre all'accesso alla gestione delle applicazioni.

1. Vai su Impostazioni → App → Applicazioni private.
2. Apri (o crea) l'applicazione privata.
3. Scorri fino alla sezione Webhook, card Webhook di organizzazione.
4. Clicca Aggiungi 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. Clicca Salva.

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

I webhook sono legati all'organizzazione, non alla singola applicazione privata: quelli che vedi nella card valgono per l'intera organizzazione, indipendentemente dall'app usata per crearli.

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. Ogni payload contiene:

• organization — il dominio dell'organizzazione che ha generato l'evento.
• event — il topic dell'evento (es. donation.created).
• object — l'oggetto interessato dall'evento.
• idempotency_key — identificativo univoco della chiamata. Usalo per deduplicare: la stessa chiave può arrivare più volte, il tuo endpoint deve gestirla in modo idempotente.

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.

Dettagli richiesta

Di seguito alcuni esempi di richiesta lanciata da Riseact verso il tuo webhook.

Webhooks di sostenitore

{
  "organization": "your-org-domain",
  "object": {
    "id": 75835,
    "create_date": "2023-08-17T16:10:45.354192+00:00",
    "update_date": "2023-08-17T16:10:45.367332+00:00",
    "image": "",
    "business_name": null,
    "first_name": "first name",
    "last_name": "last name",
    "supporter_type": "INDIVIDUAL",
    "email": "test@email.com",
    "phone": "phone",
    "mobile": "mobile",
    "sex": "MALE",
    "date_of_birth": "1970-01-01",
    "place_of_birth": "Place of birth",
    "ssn": "ssn",
    "vat": "vat",
    "address": "address",
    "address2": "secondary address",
    "city": "city",
    "locality": "locality",
    "country": "IT",
    "postal_code": "code",
    "certification_url": null,
    "privacy": false,
    "email_marketing": false,
    "phone_marketing": false,
    "sms_marketing": false,
    "postal_marketing": false,
    "profilation_marketing": false,
    "note": "notes",
    "tags": [],
    "external_ref": null,
    "source_campaign": null,
    "organization": 33,
    "application": 1,
    "stripe_customer_id": null
  },
  "event": "supporter.created",
  "idempotency_key": "b1e0c9a2-4f3d-4e2a-9c1b-6a7f8d0e2c34"
}

Webhooks di checkout

{
  "organization": "your-org-domain",
  "object": {
    "id": 901,
    "create_date": "2023-08-17T16:15:52.746141+00:00",
    "update_date": "2023-08-17T16:15:52.746165+00:00",
    "state": "OPEN",
    "amount": 10,
    "completed_date": null,
    "donation": null,
    "supporter": 75835,
    "frequency": null,
    "peer_campaign": null
  },
  "event": "checkout.created",
  "idempotency_key": "b1e0c9a2-4f3d-4e2a-9c1b-6a7f8d0e2c34"
}

Webhooks di pagamento

{
  "organization": "your-org-domain",
  "object": {
    "id": 230,
    "create_date": "2023-08-17T16:27:04.647182+00:00",
    "update_date": "2023-08-17T16:27:04.647204+00:00",
    "state": "PAID",
    "amount": 10,
    "payment_date": "2023-08-17T16:26:59.889000+00:00",
    "payment_method": "MANUAL",
    "donation": 229,
    "supporter": 75835,
    "frequency": 0,
    "peer_campaign": null
  },
  "event": "payment.created",
  "idempotency_key": "b1e0c9a2-4f3d-4e2a-9c1b-6a7f8d0e2c34"
}

Webhooks di donazione

{
  "organization": "your-org-domain",
  "object": {
    "id": 229,
    "create_date": "2023-08-17T16:27:04.542168+00:00",
    "update_date": "2023-08-17T16:27:04.542168+00:00",
    "code": "#1000",
    "state": "pending",
    "amount": 10,
    "frequency": 0,
    "completed_date": null,
    "campaign": 29,
    "peer_campaign": null,
    "supporter": 75835,
    "tags": [],
    "payment_method": "MANUAL"
  },
  "event": "donation.created",
  "idempotency_key": "b1e0c9a2-4f3d-4e2a-9c1b-6a7f8d0e2c34"
}