Skip to content

Overview

Introduction

Webhooks may be used to automatically transfer data from the scanleads system to an external service. The initiator in the webhook context is the scanleads system.

Setup and Configuration

Webhooks may be triggered on certain events, if configured. In the configuration process the admin needs to define which webhook types should be processed by what external endpoint. It's possible to route all types to one endpoint, or to setup multiple webhook type specific external endpoints.

Authentication

At the end of the configuration process the admin receives a secret signature token that should be used to verify the integrity of the webhook initiator. This secret will be transmitted in the X-Scanleads-Signature of each http request that the scanleads system performs.

HTTP Request Head

POST /scanleads/webhook-handler HTTP/1.1
Host: example.com
Content-Type: application/json
X-Scanleads-Signature: <secret signature>

Retry Policy / Debugging

A webhook will be retried 5 times if the external endpoint does not respond with a 200 status code. The retry interval is 5 minutes. Non 200 status code response bodies will be saved inside the scanleads system for further analysis.

Webhook Types

Lead Events

Example Payload

{
  "type": "lead_created",
  "version": "1.0",
  "retry_count": 3,
  "trigger_time": "2023-10-01T12:00:00Z",
  "current_time": "2023-10-01T12:20:00Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "example@example.com",
    "lists": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Main Newsletter",
        "status": "is_signed_up",
        "meta": {
          "resource-name": "newsletter-1"
        }
      },
      {
        "id": "223e4567-e89b-12d3-a456-426614174000",
        "name": "Raffle",
        "status": "is_verified",
        "meta": {
          "resource-name": "main-raffle"
        }
      }
    ],
    "personal_data": {
      "email": "example@example.com",
      "salutation": "Herr",
      "title": "Dr.",
      "first_name": "Max",
      "last_name": "Mustermann",
      "birthdate": "1968-04-19",
      "phone": "+49 030 3994744",
      "mobile": "+49 0178 0178 0178",
      "address_line_1": "Feldmarkweg 50",
      "city": "Berlin",
      "country": "deutschland",
    },
    "consents": [
      {
        "id": "string",
        "type": "checkbox",
        "name": "Newsletter Wanted",
        "status": "active",

        "meta": {
          "key": "value"
        }
      },
      {
        "id": "string",
        "type": "external",
        "name": "Newsletter Double Opt-In",
        "status": "requested",

        "meta": {
          "key": "value"
        }
      }
    ],
    "meta": {
      "campaign_id": "1234abcd"
    },
    "delete_lead_url": "https://scanly.net/[...]"
  },
  "meta": {
    "custom_key": "some webhook handler specific data"
  }
}