Integrazione per sviluppatori
Invia ogni evento fedeltà da 7Stamp ai tuoi sistemi in tempo reale. Nessun sondaggio e nessuna chiamata programmata API. Gli eventi arrivano come richieste HTTPS POST entro pochi secondi dall'accadimento.
Usa i webhook per mantenere il tuo CRM, ERP o il backend personalizzato sincronizzato con ciò che sta accadendo dal lato fedeltà: chi si è iscritto, chi ha ricevuto un timbro, chi ha riscattato un buono, chi ha attivato un regalo di compleanno e chi è diventato inattivo. Quindi i tuoi sistemi decidono cosa fare con quei dati.
I webhook sono il lato in uscita dello stack di integrazione. Rispecchiano l'attività dei clienti e dei premi nei sistemi di cui già ti fidi per vendite, assistenza, analisi e messaggistica.
Ogni timbro, voucher, compleanno e attivazione di inattività arriva sul record del cliente nel tuo CRM. Puoi vedere la cronologia completa del programma fedeltà accanto alle vendite, alle chiamate e ai biglietti senza accedere a 7Stamp.
Quando un cliente riscatta un voucher, invia un ringraziamento SMS dal tuo gateway SMS esistente. Quando un cliente raggiunge l'obiettivo, pubblica un festeggiamento in Slack. Quando qualcuno diventa inattivo, inoltra il caso al tuo account manager.
Trasmetti eventi nel tuo strumento BI, nel magazzino o nella pipeline di riconciliazione. Confronta i riscatti dei voucher con le ricevute POS e calcola la fedeltà ROI secondo i tuoi parametri.
Il tuo endpoint dovrebbe accettare HTTPS POST, convalida la forma della richiesta, persiste o accoda l'evento, quindi restituisce una risposta 2xx riuscita. Non effettuare una chiamata lenta al CRM o un messaggio prima della conferma se è possibile metterla in coda in modo sicuro.
Ogni evento correlato può contenere External ID e External Source opzionale che hai utilizzato durante la creazione o la scansione della carta. Utilizza questa coppia per aggiornare il tuo CRM, POS o il record dell'ordine senza indovinare da un nome o da un'e-mail.
Memorizza una chiave di elaborazione durevole o un'impronta digitale dell'evento prima di attivare effetti collaterali. Se il destinatario vede di nuovo la stessa consegna, non dovrebbe aggiungere una nota, un voucher o un messaggio CRM duplicato. Tratta l'endpoint URL come un segreto.
json {
"entity": "card_event",
"action": "created",
"entity_id": 707,
"event_id": "8f05e58decec48e09d328f0edebbacf6",
"profile_id": 2,
"profile_name": "Your Business",
"profile_lang": "en",
"data": {
"event_type": "SCAN",
"scanned_at": "2026-10-01T09:19:24.179424",
"user_card_id": 10,
"card_template_id": 14,
"card_template_name": "Collect your stamps!",
"stamps_added": 3,
"stamps_before": 1,
"stamps_after": 4,
"amount": null,
"external_order_id": "ORDER-1001",
"workplace": { "id": 4, "name": "Bar Counter" },
"device_type": null,
"external_id": "odoo_contact_8821",
"external_source": "odoo",
"issued_vouchers": [
{
"id": 174,
"unique_code": "100425813507",
"stamp_number": 4,
"issued_at": "2026-10-01T09:19:24.191836",
"expires_at": "2027-01-01T23:59:59",
"status": "ACTIVE",
"voucher_template_id": 58,
"voucher_description": "Free coffee",
"voucher_image_url": "https://..."
}
],
"achieved_goals": [],
"user": {
"id": 2,
"name": "Anna",
"full_name": "Anna Smith",
"email": "anna@example.com",
"telegram_chat_id": null,
"telegram_username": null,
"whatsapp_phone": null,
"birth_date": null
}
}
}Crea un endpoint HTTPS nel tuo backend, livello di integrazione CRM, webhook Make o Zapier Catch Hook. Make assicurati di controllare la destinazione prima di copiarne URL.
In 7Stamp Admin, apri Stamp Cards → API & Integrations → Webhooks.
Aggiungi l'URL dell'endpoint. Il webhook riceve ogni evento della carta del profilo, quindi filtra per data.event_type nel tuo sistema ricevente.
Salva le impostazioni del profilo, quindi attiva una scansione di prova usa e getta o un'azione della scheda per produrre un evento.
Ispeziona il carico utile ricevuto. Abbina External ID e External Source al record previsto e conferma che il ricevitore restituisce una risposta positiva.
Abilita CRM, voucher o effetti collaterali dei messaggi solo dopo aver gestito e monitorato gli errori in modo replay-safe.
In Make, usa Webhooks → Custom webhook per generare una ricezione URL e incollala in 7Stamp profilo. In Zapier, utilizzare Webhooks by Zapier → Catch Hook per lo stesso scopo. Il profilo 7Stamp possiede la sottoscrizione perché l'attuale API non espone endpoint di registrazione automatica del webhook.
Usa la sezione Webhooks del riferimento pubblico OpenAPI come fonte per lo schema attuale del payload. Il corpo è una busta: profile_id e profile_name indicano il profilo 7Stamp, event_id identifica l'evento e l'evento della carta vero e proprio si trova in data (per un URL di Make o Zapier la chiave è card_event). Ogni consegna è firmata in un'unica intestazione, X-Webhook-Signature: t=…,s=…. Calcola l'HMAC-SHA256 con il segreto del webhook su t seguito dal corpo grezzo della richiesta, codificalo in esadecimale e confrontalo con s; il segreto si trova nella pagina del webhook in 7Stamp Admin. Usa X-Webhook-Event-Id per scartare le consegne ripetute: un nuovo tentativo viene firmato di nuovo con un nuovo t. Puoi anche proteggere l'endpoint con Basic Auth. Richiedi HTTPS e tieni l'URL del sistema ricevente fuori dai log pubblici.
No. Un webhook 7Stamp riceve ogni evento della carta del profilo. Filtra per data.event_type nel tuo sistema ricevente; in Make e Zapier l'evento arriva sotto card_event, quindi filtra per card_event.event_type.
Crea il webhook ricevente in Make o un Catch Hook in Zapier, copia il URL generato, quindi incollalo nelle impostazioni del webhook del profilo 7Stamp e invia un evento di prova.
Usa data.external_id e, se presente, data.external_source: tornano in ogni webhook per le carte che hai emesso tramite l'API con il tuo ID. Un cliente che ha preso la carta da solo non ha un External ID, quindi abbinalo tramite data.user.email. Un indirizzo Apple “Hide My Email” è un indirizzo di inoltro, non quello presente nel tuo CRM.
Dividi l'intestazione X-Webhook-Signature in t e s, calcola l'HMAC-SHA256 con il segreto del webhook preso da 7Stamp Admin su t seguito dal corpo grezzo della richiesta, codificalo in esadecimale e confrontalo con s. Prendi t esattamente come è stato inviato e il corpo come i byte grezzi ricevuti, prima di qualsiasi parsing JSON. Scarta una consegna il cui X-Webhook-Event-Id hai già elaborato: un nuovo tentativo viene firmato di nuovo con un nuovo t.
Pagine correlate
Passaggio successivo
Crea un ricevitore, incolla il suo HTTPS URL nel profilo, esegui una scansione usa e getta e convalida il External ID corrispondente prima di abilitare l'automazione a valle.