Webhook

Webhook in entrata da Whop e Shopify che WooshPayment riceve. Webhook custom in uscita verso merchant in roadmap.

Webhook custom merchant: roadmap. WooshPayment non emette ancora webhook in uscita verso endpoint configurati dal merchant. Quando un cliente paga, lo stato si propaga al tuo Shopify/Woo tramite l'integrazione standard, non via webhook custom. Webhook merchant outgoing è in lavorazione.

Oggi questa pagina documenta i webhook in entrata che WooshPayment riceve da Whop e Shopify.

Webhook ricevuti da Whop

Endpoint che esponiamo per ricevere notifiche pagamento da Whop:

POST https://api.wooshpayment.com/webhooks/whop/payment-update

Configura questo endpoint sul tuo Whop dashboard → Settings → Webhooks. Whop firma ogni payload con HMAC-SHA256 usando il secret della tua configurazione (memorizzato come WHOP_WEBHOOK_SECRET lato platform).

Eventi processati

Evento Whop	Effetto sulla session WooshPayment
`invoice_paid`	`status → COMPLETED`, ordine creato su Shopify/Woo
`payment_succeeded`	`status → COMPLETED`
`membership_activated`	`status → COMPLETED`
`membership_went_valid`	`status → COMPLETED`
`payment.failed` / `payment_failed` / `invoice_payment_failed`	`status → FAILED` se non già `COMPLETED`
`payment.refunded` / `payment_refunded` / `invoice_refunded`	`status → REFUNDED` se era `COMPLETED`

Payload format

{
  "event": "invoice_paid",
  "data": {
    "id": "pay_xyz",
    "metadata": {
      "wooshpaymentSessionToken": "sess_abc"
    }
  }
}

Per legare il payment Whop a una session WooshPayment, passiamo wooshpaymentSessionToken come metadata quando creiamo l'invoice/payment intent. Quando Whop ce lo rimanda nel webhook, lo usiamo per cercare la session.

Signature verification

Whop firma con HMAC-SHA256 nel header X-Whop-Signature. La nostra verifica usa crypto.timingSafeEqual per evitare timing attacks.

I webhook con firma invalida vengono ancora persistiti in DB (per audit) ma non causano cambi di stato.

Webhook ricevuti da Shopify

Quando il merchant installa l'app, Shopify ci notifica eventi tipo:

app/uninstalled — disinstallazione dell'app, marchiamo shopifyConnected: false
customers/data_request (GDPR Compliance webhook obbligatorio)
customers/redact (GDPR Compliance webhook obbligatorio)
shop/redact (GDPR Compliance webhook obbligatorio)

Tutti su https://api.wooshpayment.com/webhooks/shopify/*.

Webhook custom merchant — roadmap

Quando rilasceremo i webhook outgoing custom, il flusso sarà:

Dashboard → "Webhook" → "Aggiungi endpoint" con URL HTTPS + lista eventi
WooshPayment manda POST firmato HMAC al tuo endpoint quando l'evento accade
Retry esponenziale fino a 24h, replay manuale dalla dashboard
Dead-letter queue per eventi non recapitabili

Eventi pianificati:

session.completed (pagamento OK)
session.refunded
session.abandoned
dispute.created
dispute.resolved

ETA: post-launch.

Workaround attuale

Per ora, se ti serve sapere quando un ordine WooshPayment viene completato:

Shopify: usa i webhook nativi Shopify orders/paid o orders/create — noi creiamo l'ordine sul tuo Shopify subito dopo invoice_paid Whop, quindi i tuoi webhook Shopify si attivano automaticamente
WooCommerce: usa i webhook Woo order.created o order.updated — stessa logica

Questo è il pattern più semplice oggi e copre il 95% dei casi d'uso.