> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/developer-tools/webhooks.md).

# Webhooks

Webhooks send data to your server when important events occur in your referral/affiliate program. This lets you deliver rewards automatically or update users in your database.

{% hint style="info" %}
**Using AI?** Follow [Build with AI](https://docs.growsurf.com/build-with-ai).
{% endhint %}

## Example scenarios

Here are a few scenarios in which you would use webhooks:

* If you have an internal points system, webhooks allow you to add credits to users in your database whenever a referral occurs.
* When a new participant joins your referral or affiliate program, webhooks let you store their unique referral link (along with other participant details) in your database.
* For referral programs, use `PARTICIPANT_REACHED_A_GOAL` to deliver approved rewards in your own system. Follow [Referral Program Workflow](/getting-started/referral-program-workflow.md) for approval handling, double-sided rewards, and repeated deliveries.
* For affiliate programs, use `NEW_COMMISSION_ADDED`, `COMMISSION_ADJUSTED`, and `NEW_PAYOUT_ISSUED` to update commission and payout records in your own reporting system. Follow the [conversion-to-payout workflow](/getting-started/affiliate-program-workflow.md) and use the exact payloads in the [event reference](/developer-tools/webhooks/events-reference.md).

## Getting started

### Step 1: Add a webhook URL to your program

1. Go to the *Options* step in the *Program Editor*.
2. In the *Set up integrations* section*,* click the *Webhooks* card. Then enter your webhook endpoint URL.
3. Publish/save your changes.

<figure><img src="https://2794996218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LeklWo0yn03AhWro2Ux%2Fuploads%2F5NkccYY1vutOLCEkNmHd%2FScreen%20Shot%202026-01-23%20at%208.02.29%20PM.jpg?alt=media&amp;token=fe24173a-7fca-4359-824f-75e925f79d9a" alt=""><figcaption><p>Webhooks can be configured in the Options step in the Program Editor</p></figcaption></figure>

{% hint style="info" %}
**Tips:**

* Click *Test* next to the webhook URL to check your setup and see sample data.
* You can select the specific events to receive within the *advanced webhook settings* section.
* A total of 5 webhooks can be added per program.
  {% endhint %}

## **Retry logic**

If the first delivery fails, GrowSurf retries for several days with exponential backoff, then marks the webhook undeliverable and stops retrying.

Webhook events are stored durably, so if delivery is ever interrupted, they will be retried once service is restored. You can always check our [System Status page](https://growsurf.com/status) for webhook health.

## **Next steps**

View [Examples](/developer-tools/webhooks/examples.md) of implementing webhooks, or view what the request payloads for webhook events look like:

* [When a participant reaches a reward goal](/developer-tools/webhooks/events-reference.md#participant_reached_a_goal)
* [When a new participant is added to the program](https://docs.growsurf.com/developer-tools/webhooks/events-reference#new_participant_added)
* [When an affiliate commission is generated](https://docs.growsurf.com/developer-tools/webhooks/events-reference#new_commission_added)
* [When an affiliate commission is adjusted](https://docs.growsurf.com/developer-tools/webhooks/events-reference#commission_adjusted)
* [When an affiliate payout is issued](https://docs.growsurf.com/developer-tools/webhooks/events-reference#new_payout_issued)
* [When the program ends](https://docs.growsurf.com/developer-tools/webhooks/events-reference#campaign_ended)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.growsurf.com/developer-tools/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.