Skip to main content

Webhook di Organizzazione

Riseact chiama il tuo endpoint quando in un'organizzazione succede qualcosa: un sostenitore creato, un checkout pagato e così via.

I webhook di organizzazione ricevono solo gli eventi di un'organizzazione. Per una partner app che deve ricevere gli eventi di tutte le organizzazioni che l'hanno installata, usa i webhook di applicazione.

Impostare un webhook

Si gestiscono nel dettaglio di un'applicazione privata; basta l'accesso alla gestione delle applicazioni.

  1. Vai su Impostazioni > App > Applicazioni private e apri (o crea) l'applicazione.
  2. Nella sezione Webhook, card Webhook di organizzazione, clicca Aggiungi webhook.
  3. Scegli gli eventi e inserisci l'URL HTTPS che riceverà le POST.
  4. Clicca Salva.

Dalla card modifichi o elimini i webhook registrati. Valgono per tutta l'organizzazione, qualunque applicazione privata li abbia creati.

Eventi disponibili

EventoDescrizione
supporter.createdUn nuovo sostenitore è stato creato
supporter.updatedUn sostenitore è stato aggiornato
supporter.deletedUn sostenitore è stato eliminato
checkout.createdUn nuovo checkout è stato aperto
checkout.updatedUn checkout è stato aggiornato
checkout.paidUn checkout è stato completato con pagamento
checkout.closedUn checkout è stato chiuso
donation.createdUna nuova donazione è stata creata
donation.updatedUna donazione è stata aggiornata
donation.deletedUna donazione è stata eliminata
donation.revokedUna donazione è stata revocata: a mano, per il rimborso del suo ultimo pagamento o per il pagamento fallito di una donazione singola
payment.createdUn nuovo pagamento è stato registrato
payment.updatedUn pagamento è stato aggiornato
campaign.createdUna nuova campagna è stata creata
campaign.updatedUna campagna è stata aggiornata
campaign.deletedUna campagna è stata eliminata

Consegna delle chiamate

Riseact invia una POST JSON all'URL registrato. Il payload contiene:

  • organization: il dominio dell'organizzazione;
  • event: il topic, per esempio donation.created;
  • object: l'oggetto dell'evento;
  • idempotency_key: identificativo della chiamata. La stessa chiave può arrivare più volte: usala per deduplicare.

Il timeout è di 10 secondi: rispondi subito con 2xx e fai il lavoro pesante in modo asincrono.

Se la risposta non è 2xx, o non arriva entro il timeout, Riseact ritenta la consegna dopo 1 minuto, 10 minuti, 1 ora, 6 ore e 24 ore, con lo stesso payload e la stessa idempotency_key. Un tentativo ripetuto può quindi arrivare dopo eventi più recenti dello stesso oggetto: confronta update_date con quello che hai salvato e scarta i payload superati.

I webhook che un'app registra tramite API, con il proprio token, sono firmati con il client secret dell'app, nello stesso formato dei webhook di applicazione. Quelli creati dall'admin non sono firmati: per verificarne la provenienza usa un percorso segreto o un token in query string nell'URL.

Se l'app privata ha un URL impostato riceve anche la chiamata di disinstallazione.

Dettagli richiesta

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"
}

Fonte: https://dev.riseact.org/docs/private-apps/organization-webhooks. Copia automatica da dev.riseact.org: non modificare qui, le modifiche vanno fatte sulla documentazione Docusaurus.

Back to top