Send data to your systems with webhooks

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.