Webhooks Integration Guide

To enable webhooks to be sent from your Scorecard go to Integrate > Webhooks and click Connect to add the URL that you'd like to receive webhooks too.

Note: You must provide a secure (https) URL that can receive POST requests

Once you have provided your secure URL to receive post requests you will be able to specify a secret key and which events you'd like to receive.

Events

There are 4 possible events you may receive as a webook:


Quiz Started (QUIZ_STARTED)

This webhook is sent when somebody answers the first question in your quiz. If your lead form is configured to show before the quiz questions, the lead form data such as name/email will included in the webhook payload.

Quiz Finished (QUIZ_FINISHED)

This webhook is sent when somebody answers the last question in your quiz. If your lead form is configured to show before the quiz questions, the lead form data such as name/email will included in the webhook payload however if it's configured to show at the end of the quiz questions this webhook will be sent prior to the lead form being shown/completed.

Lead Details Updated (LEAD_DETAILS_UPDATED)

This webhook is sent if a lead subsequently changes their sign up details after receiving their results. Usually via a form on your result page.

Lead Signed Up (LEAD_SIGNED_UP)

This webhook is sent when a lead provides their details (normally name and email) via the lead form. If your lead form is configured to show before the quiz questions this will be sent before any quiz questions are answered and will therefore the request payload will only include the lead form data. If the lead form is set after the quiz questions, all quiz answers and data will be available in the request payload.

Webhook Payload Format


General structure

{
"event_name" : "Event name",
"data": {} // - Response data
}

Example QUIZ_STARTED webhook

{
  "event_name" : "QUIZ_STARTED",
  "data"       : {
      "id": "1e11c712-c4f7-48e9-8bc7-7d86ea273a6f",
      "status": "Started",
      "key": "64b00a39ce128979457258",
      "first_name": null,
      "last_name": null,
      "email": "example@example.com",
      "started_at": "2023-07-06T08:12:09.000Z",
      "opt_in": true,
      "opt_in_detail": "Implied",
      "utm_source": null,
      "utm_campaign": null,
      "utm_medium": null,
      "utm_term": null,
      "utm_content": null,
      "ip_address": "172.23.0.1",
      "lead_form_questions": [ //- possible if we added fields to lead form.
          {
              "id": "01a725d2-bd2c-4aa0-a799-6d6fc8e7ac9d",
              "question": "Question",
              "answers": [
                  {
                      "answer": "Answer"
                  }
              ]
          },
      ],
      "quiz_questions": [],
      "abandon_email_url": "https://example.scoreapp.com/continue/64a6775915bf6092267456"
  }
};

Example QUIZ_FINISHED webhook

{
  "event_name" : "QUIZ_FINISHED",
  "data"       : {
      "id": "1e11c712-c4f7-48e9-8bc7-7d86ea273a6f",
      "status": "Finished",
      "key": "64b00a39ce128979457258",
      "first_name": null,
      "last_name": null,
      "email": "example@example.com",
      "started_at": "2023-07-06T08:25:25.000Z",
      "opt_in": true,
      "opt_in_detail": "Implied",
      "utm_source": null,
      "utm_campaign": null,
      "utm_medium": null,
      "utm_term": null,
      "utm_content": null,
      "ip_address": "172.23.0.1",
      "lead_form_questions": [ //- possible if we added fields to lead form.
          {
              "id": "01a725d2-bd2c-4aa0-a799-6d6fc8e7ac9d",
              "question": "Question",
              "answers": [
                  {
                      "answer": "Answer"
                  }
              ]
          },
      ],
      "quiz_questions": [
          {
              "id": "0f9d99a8-1835-46d7-bb1f-86b579195797",
              "question": "Question 1",
              "answers": [
                  {
                      "answer": "No"
                  }
              ]
          },
          {
              "id": "d9cadc83-50df-442c-aeb2-a0878e3e7fb7",
              "question": "Question 2",
              "answers": [
                  {
                      "answer": "5"
                  }
              ]
          },
          {
              "id": "ea795cc9-e437-4734-a85a-34837dccbb2d",
              "question": "Question 3",
              "answers": [
                  {
                      "answer": "Answer 1"
                  },
                  {
                      "answer": "Answer 2"
                  },
                  {
                      "answer": "Answer 3"
                  }
              ]
          },
      ],
      "finished_at": "2023-07-06T08:25:29.000Z",
      "report": "https://example.scoreapp.com/results/64a67a753fbb6186785302/pdf",
      "lowest_category": {
          "id": "433cad86-ce58-4755-9b97-16cbbea42b15",
          "title": "Category 2"
      },
      "highest_category": {
          "id": "3fc9bef7-c890-4ec7-9414-f13929ac4e38",
          "title": "Category 1"
      },
      "total_score": {
          "actual": "67.00",
          "percent": 54,
          "denominator10": 5.36,
          "tier": "medium"
      },
      "category_scores": [
          {
              "actual": "56.00",
              "percent": 50,
              "denominator10": 4.96,
              "tier": "medium",
              "category": {
                  "id": "e6b19afd-891c-41cc-ab44-c7e2e8485acd",
                  "title": "Category 1"
              }
          },
          {
              "actual": "4.00",
              "percent": 33,
              "denominator10": 3.33,
              "tier": "low",
              "category": {
                  "id": "ff35527a-2cb8-4ed0-b142-5bad8ac14818",
                  "title": "Category 2"
              }
          },
      ],
      "result_url": "https://example.scoreapp.com/results/64a67a753fbb6186785302",
      "audiences": [
          {
              "id": "30672ea7-8515-46bd-bde1-09b8e0986873",
              "name": "Audience 1"
          },
          {
              "id": "278e64c9-71e4-4cb1-bc70-009e33357336",
              "name": "Audience 2"
          }
      }
};

Example LEAD_SIGNED_UP webhook

{
  "event_name" : "LEAD_SIGNED_UP",
  "data"       : {
      "id": "1e11c712-c4f7-48e9-8bc7-7d86ea273a6f",
      "status": "Started",
      "key": "64b00a39ce128979457258",
      "first_name": null,
      "last_name": null,
      "email": "example@example.com",
      "started_at": "2023-07-06T08:12:09.000Z",
      "opt_in": true,
      "opt_in_detail": "Implied",
      "utm_source": null,
      "utm_campaign": null,
      "utm_medium": null,
      "utm_term": null,
      "utm_content": null,
      "ip_address": "172.23.0.1",
      "lead_form_questions": [ //- possible if we added fields to lead form.
          {
              "id": "01a725d2-bd2c-4aa0-a799-6d6fc8e7ac9d",
              "question": "Question",
              "answers": [
                  {
                      "answer": "Answer"
                  }
              ]
          },
      ],
      "quiz_questions": [],
      "abandon_email_url": "https://example.scoreapp.com/continue/64a6775915bf6092267456"
  }
};

Example LEAD_DETAILS_UPDATED webhook

{
  "event_name" : "LEAD_DETAILS_UPDATED",
  "data"       : {
      "id": "1e11c712-c4f7-48e9-8bc7-7d86ea273a6f",
      "status": "Finished",
      "key": "64b00a39ce128979457258",
      "first_name": null,
      "last_name": null,
      "email": "example.changed@example.com",
      "started_at": "2023-07-06T08:25:25.000Z",
      "opt_in": true,
      "opt_in_detail": "Implied",
      "utm_source": null,
      "utm_campaign": null,
      "utm_medium": null,
      "utm_term": null,
      "utm_content": null,
      "ip_address": "172.23.0.1",
      "lead_form_questions": [ //- possible if we added fields to lead form.
          {
              "id": "01a725d2-bd2c-4aa0-a799-6d6fc8e7ac9d",
              "question": "Question",
              "answers": [
                  {
                      "answer": "Answer changed"
                  }
              ]
          },
      ],
      "quiz_questions": [
          {
              "id": "0f9d99a8-1835-46d7-bb1f-86b579195797",
              "question": "Question 1",
              "answers": [
                  {
                      "answer": "No"
                  }
              ]
          },
          {
              "id": "d9cadc83-50df-442c-aeb2-a0878e3e7fb7",
              "question": "Question 2",
              "answers": [
                  {
                      "answer": "5"
                  }
              ]
          },
          {
              "id": "ea795cc9-e437-4734-a85a-34837dccbb2d",
              "question": "Question 3",
              "answers": [
                  {
                      "answer": "Answer 1"
                  },
                  {
                      "answer": "Answer 2"
                  },
                  {
                      "answer": "Answer 3"
                  }
              ]
          },
      ],
      "finished_at": "2023-07-06T08:25:29.000Z",
      "report": "https://example.scoreapp.com/results/64a67a753fbb6186785302/pdf",
      "lowest_category": {
          "id": "433cad86-ce58-4755-9b97-16cbbea42b15",
          "title": "Category 2"
      },
      "highest_category": {
          "id": "3fc9bef7-c890-4ec7-9414-f13929ac4e38",
          "title": "Category 1"
      },
      "total_score": {
          "actual": "67.00",
          "percent": 54,
          "denominator10": 5.36,
          "tier": "medium"
      },
      "category_scores": [
          {
              "actual": "56.00",
              "percent": 50,
              "denominator10": 4.96,
              "tier": "medium",
              "category": {
                  "id": "e6b19afd-891c-41cc-ab44-c7e2e8485acd",
                  "title": "Category 1"
              }
          },
          {
              "actual": "4.00",
              "percent": 33,
              "denominator10": 3.33,
              "tier": "low",
              "category": {
                  "id": "ff35527a-2cb8-4ed0-b142-5bad8ac14818",
                  "title": "Category 2"
              }
          },
      ],
      "result_url": "https://example.scoreapp.com/results/64a67a753fbb6186785302",
      "audiences": [
          {
              "id": "30672ea7-8515-46bd-bde1-09b8e0986873",
              "name": "Audience 1"
          },
          {
              "id": "278e64c9-71e4-4cb1-bc70-009e33357336",
              "name": "Audience 2"
          }
      }
};

Failures and Retries

If the URL to which we send a webhook fails to send a response with a 2xx status code we will consider the call as failed. The call will also be considered failed if the remote app doesn't respond within 10 seconds

If the call fails we will attempt to resend the webhook up to a maximum of 5 times.


Optional Webhook Header / Secret Key (Recommended)

If you provide an optional “WEBHOOK SECRET KEY”, a header (Scoreapp-Signature ) will be included with each webhook request containing a hashed string allowing you to securely validate the authenticity of the request.

The following is example PHP code that would verify the webhook request using this method

public function webhookHandler(Request $request)
{
    $signature = $request->header('Scoreapp-Signature');
    $signingSecret = 'Your webhook secret key';
    $computedSignature = hash_hmac('sha256', $request->getContent(), $signingSecret);
    $valid = hash_equals($signature, $computedSignature);
    if (!$valid) {
       return response('Unauthorized', 401);
    }
    
    // your code goes here
    
    return response('Webhook handled', 200);
}

Still need help? Contact Us Contact Us