> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yuko.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time HTTP callbacks when Yuko events happen — the right way to integrate Yuko with anything else.

<Note>
  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Integrations → Webhooks
</Note>

## What webhooks do

Webhooks notify your endpoint the moment a Yuko event happens — a customer earned points, a reward was redeemed, a tier changed. Faster, cheaper and more reliable than polling the REST API.

## When to use

* You're syncing Yuko data into your data warehouse.
* You're triggering downstream automations (Slack alerts, internal dashboards).
* You're integrating Yuko with a tool that doesn't have a Yuko connector.
* You're building real-time UX around loyalty events.

## Available events

* `customer.points.credited`
* `customer.points.debited`
* `customer.reward.issued`
* `customer.reward.redeemed`
* `customer.tier.changed`
* `customer.referral.completed`
* `membership.contract.activated`
* `membership.contract.cancelled`
* `membership.contract.failed`

More events may be available depending on your Yuko version. Check the dashboard for the canonical list.

## Before you start

<Check>Yuko app is installed on your Shopify store — see [Install Yuko on Shopify](/installation-and-setup/install-on-shopify).</Check>
<Check>The Yuko **Theme App Embed** is enabled in your active theme.</Check>
<Check>Your loyalty program is enabled at **Shopify admin → Apps → Yuko Loyalty → Loyalty → Settings**.</Check>
<Check>Points label and currency are configured.</Check>

<Check>You have a publicly reachable HTTPS endpoint that can receive POST requests.</Check>
<Check>The endpoint can verify a signature on the request (recommended).</Check>

## Setup

<Steps>
  <Step title="Open Webhooks">
    Go to **Apps → Yuko Loyalty → Integrations → Webhooks**.
  </Step>

  <Step title="Create a subscription">
    Click **New webhook**. Enter:

    * **Endpoint URL** — your HTTPS receiver.
    * **Events** — pick which events to receive.
    * **Description** — a label for your records.
  </Step>

  <Step title="Copy the signing secret">
    Yuko shows a one-time signing secret. Store it in your endpoint's environment.
  </Step>

  <Step title="Verify with a test event">
    Click **Send test**. Check your endpoint received and accepted the payload.
  </Step>
</Steps>

## Payload format

Every webhook is a POST with JSON:

```json theme={null}
{
  "event": "customer.points.credited",
  "created_at": "2026-05-06T10:31:00Z",
  "data": {
    "customer": { "id": "...", "email": "..." },
    "points_value": 50,
    "campaign": { "id": "...", "name": "Place an Order" }
  }
}
```

Full payload schemas per event are in the dashboard.

## Verifying signatures

Every webhook includes an `X-Yuko-Signature` header. Verify:

1. Compute HMAC-SHA256 of the request body using your signing secret.
2. Compare to the header (constant-time).
3. Reject if it doesn't match.

## Retries and idempotency

* Yuko retries failed deliveries with exponential backoff for 24 hours.
* Each delivery has a unique `event_id` — use it to dedupe on your side.
* Respond `2xx` within 30 seconds for success.

## Best practices

<Tip>**Verify signatures.** It's the only way to be sure the request came from Yuko.</Tip>
<Tip>**Be idempotent.** Use the `event_id` to ignore duplicates from retries.</Tip>
<Tip>**Respond fast.** Push the actual processing to a queue and respond `200` quickly.</Tip>
<Tip>**Monitor delivery failures.** The webhook dashboard shows recent failures — check it weekly.</Tip>

## FAQs

<AccordionGroup>
  <Accordion title="What if my endpoint goes down?">
    Yuko retries with exponential backoff for 24 hours. After that, the event is dropped from the queue but visible in the dashboard's failed-deliveries log.
  </Accordion>

  <Accordion title="Can I subscribe multiple endpoints to the same event?">
    Yes — create one webhook per endpoint.
  </Accordion>

  <Accordion title="How do I rotate the signing secret?">
    Edit the webhook and click **Rotate secret**. The old secret stops working after a 24-hour overlap.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="REST API" icon="code" href="/integrations/rest-api">
    Read and write Yuko data programmatically.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/integrations/webhooks">
    Receive real-time event notifications.
  </Card>

  <Card title="Shopify Flow" icon="shop" href="/integrations/shopify-flow">
    Trigger Shopify Flow workflows from Yuko events.
  </Card>

  <Card title="Klaviyo" icon="envelope" href="/integrations/klaviyo">
    Sync customers, points and tier data into Klaviyo.
  </Card>

  <Card title="Omnisend" icon="envelope" href="/integrations/omnisend">
    Sync loyalty data into Omnisend.
  </Card>

  <Card title="WhatsApp" icon="comments" href="/integrations/whatsapp">
    Send transactional loyalty messages via 7 supported WhatsApp Business API providers.
  </Card>

  <Card title="Retainful" icon="envelope-open-text" href="/integrations/retainful">
    Email marketing & abandoned cart recovery.
  </Card>

  <Card title="Facebook & Instagram" icon="facebook" href="/integrations/facebook-instagram">
    Social verification for like / follow campaigns.
  </Card>

  <Card title="Google Business" icon="google" href="/integrations/google-business">
    Google Business profile and reviews.
  </Card>

  <Card title="Custom Apps" icon="puzzle-piece" href="/integrations/custom-apps">
    OAuth or API-key based custom integrations.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Book a Free Setup Call" icon="phone" href="https://cal.com/rameshelamathi/yuko-demo">
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  </Card>

  <Card title="Contact Support" icon="life-ring" href="https://yuko.so/support/">
    Visit our support hub for help articles, live chat and ticket submission.
  </Card>

  <Card title="Browse the Guides" icon="book" href="/getting-started/welcome">
    Documentation across loyalty, referrals, memberships and more.
  </Card>

  <Card title="Install Yuko" icon="shop" href="https://apps.shopify.com/yuko">
    Add Yuko to your Shopify store from the Shopify App Store.
  </Card>
</CardGroup>