---
title: "Send data to your systems with webhooks"
description: "Get a request to your own URL when someone signs up, takes part or wins, with a signed payload, basic auth, a custom payload and a log of every delivery."
url: https://scratcher.io/help/developers/webhooks
language: en
---

1. [Help center](https://scratcher.io/help)
2. [API, webhooks and MCP](https://scratcher.io/help/developers)
3. Send data to your systems with webhooks

# Send data to your systems with webhooks

Get a request to your own URL when someone signs up, takes part or wins, with a signed payload, basic auth, a custom payload and a log of every delivery.

A webhook sends data to a URL you choose the moment something happens, for example when someone takes part in a campaign or wins a prize. Your developer sets up the system that receives it.

Webhooks are part of the plans that include **Webhooks & API** (Basic and up).

## Campaign webhooks or account webhooks?

- **Campaign webhooks** are set up in the campaign editor and fire for that campaign only. They have the events "Every time a lead participates in a campaign" and "When a lead wins a prize", and the most options.
- **Account webhooks** are set up under **Settings** > **Webhooks**. They have the event "When a new lead is created": it fires once per person, the first time they are added to your leads, whatever campaign they came from.

## Add a webhook to a campaign

1. Open the campaign in the editor and go to **Connect** > **Webhooks**.
2. Click **Add webhook**.
3. Enter the **Payload URL**. It must start with https: "We only support webhooks over HTTPS to ensure that the data sent remains secure."
4. Choose the **Content type**: **application/json** or **application/x-www-form-urlencoded**.
5. Choose the **Method**. The form starts on **GET**, which sends the data in the URL. Choose **POST** to send it in the body, which is what most systems expect.
6. Under **Authentication** (only for POST), choose **Basic Auth** if your URL needs a username and password, and fill in **Username** and **Password**. Otherwise keep **None**.
7. Enter a **Secret** to sign the requests (recommended). See "Check the signature" below.
8. Turn on **Log response body** if you want to see what your system answers. "Enable to store the response body for debugging."
9. Keep **Active** on. "We will only deliver events if the webhook is active."
10. Choose the event: "Every time a lead participates in a campaign" or "When a lead wins a prize".
11. Turn on **Custom payload** if you want to decide the fields yourself (see below).
12. Click **Add webhook**. You see "Webhook added".

The **Webhooks** panel lists the campaign's webhooks with **Active** or **Inactive**, and **Last delivery failed** if the latest request failed. Use **Actions** to **Edit**, **See deliveries** or **Delete** a webhook. When you edit a webhook, leave **Secret** blank to keep the one you have.

## Add an account webhook

1. Go to **Settings** > **Webhooks** (under **Developers**). Your webhooks are listed under **My webhooks** (or under each lead list's name, if you have several).
2. Click the card with the plus to add a webhook. The dialog **Add webhook** says "Send a request to an external URL whenever selected events happen."
3. Fill in the **Payload URL**, **Content type** ("Select content type of the webhook"), **Method** and **Secret** as above.
4. Under **Which events should trigger the webhook?**, choose "When a new lead is created".
5. Tick "Yes, allow me to specify a customized payload (Advanced users only)" if you want your own fields.
6. Tick **Log response body** ("This webhook will log the response body") if needed, and keep **Active** ticked ("We will deliver event details when this hook is triggered").
7. Click **Add webhook**.

Click a webhook to change it (**Save changes**), set a **New secret**, open **Show deliveries** or **Delete webhook** ("This action cannot be reverted!").

## What is sent

By default, the body has an `event` (the event's name: `lead_created_on_campaign`, `new_campaign_winner` or `lead_created`) and a `data` object:

- `campaign`: the campaign's `id` and `name` (campaign webhooks)
- `lead`: the lead's form fields by their field key (for example `first_name`), plus `id`, `phone_number` and `created_at`
- `lead.permissions`: for each consent checkbox, whether it was accepted, the text, the date and the IP address (campaign webhooks)
- `participant`: the `channel` the person came from and when they took part (campaign webhooks)
- `quiz`: the answers to named quiz questions, also under readable names that start with "Simple"
- `prize`: the prize's `id`, `name`, `value`, `coupon_code` and when it was won (winner webhooks)

Empty values are left out, and so are consents that weren't accepted. With the GET method, the same data is sent as query parameters in the URL.

## Custom payload

With **Custom payload** on, only the fields you choose are sent, and there is no `event` wrapper.

1. Under **Data mapping**, click **Add mapping**.
2. Type the **Field name** your system expects. Use letters, numbers, dashes and underscores.
3. Choose the Scratcher field to send ("Group → Field"), or **Custom value** and type a fixed **Value**.
4. Repeat for each field. Remove one with the bin (**Remove** or **Remove data mapping**).

## Check the signature

If you set a secret, every request has an `X-Hub-Signature` header: `sha1=` followed by an HMAC-SHA1 hash of the JSON-encoded payload (the body as described above), using your secret as the key. Compute the same on your side and compare, to be sure the request came from Scratcher.

## Deliveries and retries

- If your URL doesn't answer or returns an error (status 400 or higher), Scratcher tries again twice: after 5 seconds and after a minute.
- Redirects aren't followed, so use the final URL.
- Open the deliveries (**See deliveries** in the campaign, **Show deliveries** for account webhooks) to see each request and response. Each delivery shows its **ID**, the **Request** and the **Response** with its status code (and the **Response body** if you log it). Use **copy** to copy a payload.
- Turn on **Show only failed deliveries** to see only the problems. The top shows "Failed deliveries in the last 60 days".
- Click **Retry** to send a delivery again: "The webhook is being resent."
- "Webhook delivery logs are retained for 60 days."

## Troubleshooting

- "The ... field must use HTTPS.": the **Payload URL** starts with http. Use https.
- Every delivery fails with no response: the URL can't be reached from the internet, for example a local or internal address. Use a public URL.
- Your system gets no data: the method is **GET**, so the data is in the URL. Switch to **POST**.
- A field your system expects is missing: it was empty, or the consent wasn't accepted. Make your system treat missing fields as empty.

API, webhooks and MCP

- [Get started with the REST API](https://scratcher.io/help/developers/rest-api)
- [Send data to your systems with webhooks](https://scratcher.io/help/developers/webhooks)
- [Scratcher MCP for your own AI tools](https://scratcher.io/help/developers/mcp)

## Related articles

- [Get started with the REST API](https://scratcher.io/help/developers/rest-api): Create a personal access token with the right scopes, or register an OAuth app, and read campaigns, leads and lists from your own systems.
- [Check the delivery status and resend leads](https://scratcher.io/help/integrations/delivery-status): See which leads were sent to your tools, understand the error messages, fix the problem and send them again.
- [Connect 8,000+ apps with Zapier](https://scratcher.io/help/integrations/zapier): Send new sign-ups from Scratcher to Google Sheets, Slack, your CRM or thousands of other apps with Zapier.

## Still need help?

Real people are here to help. If you already use Scratcher, the quickest way is the chat inside the platform.

- **[Chat with us](https://platform.scratcher.io/login)**

    Log in and click the chat button in the bottom-right corner. Rex answers right away, and our team is a click away.
- **[Book a meeting](https://scratcher.io/book-a-meeting)**

    A free 30-minute video call with our team: a tour, campaign ideas or help with your setup.
- **[Email us](mailto:contact@scratcher.io)**

    Write to contact@scratcher.io and we will get back to you.