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

# Webhooks Setup

> Receive real-time gift, order, and delivery events. Configure endpoints, verify signatures, and test locally before going live.

## Overview

Webhooks allow your application to receive real-time, asynchronous notifications when specific events occur within the Snappy system. Instead of constantly polling the API for updates, Snappy will push data to your server as soon as a gift is sent, viewed, or redeemed.

***

## Setup

<Steps>
  <Step title="Set up your Endpoint">
    Set up a public endpoint in your application that can accept incoming `POST` requests with a JSON payload.

    <Note>
      **Performance & Response:** Your endpoint must quickly return a `200 OK` response. If your server does not respond within **10 seconds**, Snappy will assume a delivery failure and will continue to retry sending the same event based on our retry policy.
    </Note>
  </Step>

  <Step title="Enable Webhooks in the Snappy Dashboard">
    To activate webhooks and start receiving events:

    1. Log in to your Snappy Dashboard [https://login.snappy.com/login](https://login.snappy.com/login)
    2. Navigate to **Sharing & Access** tab under the **Company Settings** page in the Snappy Dashboard ([https://login.snappy.com/company-settings/sharing-access](https://login.snappy.com/company-settings/sharing-access)).
    3. Scroll down to the 'Webhooks' section and toggle **Enable webhooks** for your organization.
    4. Click **Add Webhook**.
    5. Specify your **Destination URL**, choose the relevant **Event Types**, and click **Add**.
  </Step>

  <Step title="Verify your Setup">
    Once your webhook is saved, send a test event from the dashboard to confirm Snappy can reach your endpoint:

    1. In the **Webhooks** section of **Sharing & Access**, hover over the webhook you just added.
    2. Click **Test**.
    3. Snappy will send a template `POST` request to your destination URL containing a verification token.
    4. Confirm your endpoint received the request and returned a `200 OK`.

    <Note>
      If the test event doesn't arrive, double-check your firewall settings, your endpoint URL, and that your server is publicly reachable. You can re-run this test at any time to verify endpoint health.
    </Note>
  </Step>

  <Step title="Secure the Connection">
    To ensure that incoming requests are legitimately from Snappy and have not been tampered with, you must verify the **X-Snappy-Signature** header.

    Under your webhook configurations, you will find a **Security Token**. This token is unique to your organization and can be regenerated if it is ever compromised.

    **The Signature Logic:** The signature is a **SHA-256 hash**, where the key is your **UTF-8 encoded token** and the **raw request body** serves as the data.

    ```javascript theme={null}
    function digest(parameters: {
      clientSecret: string;
      requestBody: unknown;
    }) {
      return crypto
        .createHmac("sha256", encodeURI(parameters.clientSecret))
        .update(JSON.stringify(parameters.requestBody))
        .digest("hex");
    }

    const signature = digest({
      clientSecret,
      requestBody: request.body,
    });

    const headerSignature = request.headers["x-snappy-signature"];

    const validSignature = signature === headerSignature;
    ```
  </Step>
</Steps>

***

## Delivery & Retries

If your endpoint is unavailable or returns a non-2xx status code, Snappy will attempt to redeliver the event.

* **Retry Strategy:** We use exponential backoff over a 24-hour period.
* **Timeout:** Requests time out after 10 seconds.
* **Manual Test:** Re-run the dashboard Test action at any time to verify endpoint health.