Toggle Developers
HomeAcademy
  • Welcome
  • GraphQL
    • Getting started
    • Exploring our API
    • Authentication
    • API playground
    • Error handling
  • Key concepts
    • Overview
      • Orders, Transactions & Line Items
      • Card number formats
  • Basics
    • Create a card
    • Check a card balance
    • Redeem a card
  • Webhooks
    • Overview
      • Getting started
      • Authentication & responses
    • Events
      • Card.balance_adjusted
      • Card.card_reference_updated
      • Card.expiry_reminder
      • Card.registered
      • Card.send_recipient_email
      • Card.resend_recipient_email
      • Order.created
      • Order.cancelled
      • Order.send_receipt_email
      • Order.send_cancellation_email
      • Payment.failed
      • Payment.review_opened
      • Fulfilment.dispatched
  • Partner Guides
    • EPOS & Ordering
      • Overview
      • Accreditation
      • Configuration variables
      • Playground examples
      • Physical card orders
      • Custom validity rules
      • Balance check
      • Redemptions & top-ups
      • Reversals
    • Guest gratuity
      • Overview
      • Accreditation
      • Configuration variables
      • Playground examples
      • Creating a card
      • Cancelling a card
      • Register a card
    • CRM
      • Overview
      • Historic data via GraphQL
      • Real time data via webhooks
Powered by GitBook
On this page
  • Webhooks secret
  • Handling requests
  • Response and attempts
  1. Webhooks
  2. Overview

Authentication & responses

Webhooks secret

A webhook secret is a key used to calculate the HTTP_TOGGLE_SIGNATURE and is passed in the header of every request.

This adds a security layer between the two apps (Toggle and your App) to make sure the payload that you receive has not been tampered with. The signature is a hash of the entire payload, signed using the signing secret that we have supplied to you. Every request received by your application should compare this signature to your own, in order to ensure that it is not fraudulent.

The secret will be provided by the Toggle support team when you first set up a web hook with us.

Handling requests

Before accepting any webhook sent to you, you should verify it by checking the hashed contents.

The following example (in PHP) is how you could calculate the secret and check the payload.

function verifySignature($signingSecret, $payload) {
    $sig_header = $_SERVER['HTTP_TOGGLE_SIGNATURE'];
    $computedSignature = hash_hmac('sha256', $payload, $signingSecret);
    return hash_equals($sig_header, $computedSignature);
}

Response and attempts

We will expect a 200 response from your server. In case of failure we will attempt to dispatch the web hook another 3 times before giving up.

In order to prevent timeouts, we recommend that your server responds to webhook events prior to any logic being executed.

We will disable your endpoint if we receive invalid responses from your server over consecutive days.

PreviousGetting startedNextEvents

Last updated 3 years ago