Webhooks: Set Up & Management

Webhooks let TurnStay push real-time event notifications to your own systems the moment something happens — a payment completes, a refund is issued, a chargeback is raised. Instead of polling our API for updates, your server receives an HTTP POST with the full event data as soon as the status changes.

---

Finding webhooks in the Dashboard

Navigate to Settings → Webhooks in your TurnStay Dashboard. From there you can:

• Register and manage your webhook endpoint URL
• Enable or disable webhook delivery for your account
• View a log of recent webhook events and their delivery status

---

Registering an endpoint

1. Go to Settings → Webhooks

   Open the TurnStay Dashboard and navigate to Settings → Webhooks.

2. Enter your endpoint URL

   Paste the HTTPS URL of the server endpoint that will receive events. TurnStay will send a POST request to this URL for each event.

3. Save and verify

   Once saved, TurnStay will begin delivering events to your endpoint. Check the webhook log to confirm events are being received and your server is responding with a 2xx status.

Tip

Your endpoint must return a 2xx HTTP status code within a reasonable timeout to be considered successfully delivered. If delivery fails, TurnStay will retry the event automatically.

---

Events TurnStay sends

TurnStay fires a webhook event each time one of these objects changes status:

Event object	When it fires
payment_intent	A payment is created, processed, or encounters an error
refund	A refund is initiated or its status changes
chargeback	A chargeback is raised or updated
payout	A payout is initiated, completed, or fails

Each event includes the full current state of the object, plus a previous_attributes field showing what changed — so you always know exactly what transitioned and what it looked like before.

---

Payload structure

All webhook payloads follow the same envelope format:

{
  "object": {
    "id": "123",
    "object": "payment_intent",
    "status": "PROCESSED",
    "billing_amount": 150000,
    "billing_currency": "ZAR",
    "merchant_reference": "booking-abc-456",
    ...
  },
  "previous_attributes": {
    "status": "CONFIRMED"
  }
}

• object — the full current state of the resource that changed
• previous_attributes — only present when a field changed; shows the value before the transition (most commonly status)
• merchant_reference — your own reference, echoed back so you can match events to bookings in your system

Note

Amounts are returned in the smallest unit of the currency (e.g. cents for USD, cents for ZAR). Divide by 100 to get the display value.

---

Enabling and disabling webhooks

Webhook delivery is on by default for all accounts. You can toggle it off at any time from Settings → Webhooks in the Dashboard — useful during maintenance windows or while you’re setting up your integration.

---

Securing your endpoint

TurnStay signs each webhook payload so you can verify it genuinely came from us. Details on signature verification are available in the Developer Docs.

Tip

Always validate the webhook signature before processing an event — this protects your system from spoofed requests.

---

Need help?

If your endpoint isn’t receiving events, check the webhook log in Settings → Webhooks for delivery errors. For further help, contact us at support@turnstay.com.