SQUAKE Integration Docs
  • πŸƒOverview
  • βœ‰οΈContact form
  • ⚠️Incident form
  • πŸ—„οΈCalculation API Examples
    • 🌐Travel
      • πŸ›ŒAccommodation
        • Accommodation: SQUAKE
      • 🚌Bus
        • Bus: SQUAKE
        • Bus: DEFRA πŸ‡¬πŸ‡§
      • πŸš—Car
        • Car: ACRISS
        • Car: DEFRA πŸ‡¬πŸ‡§
        • Car: EEA πŸ‡ͺπŸ‡Ί
        • Car: EPA πŸ‡ΊπŸ‡Έ
      • 🀝Event
        • Event: HCMI & CHSB
      • ⛴️Ferry
        • Ferry: ADEME πŸ‡«πŸ‡·
      • ✈️Flight
        • Flight: ADEME πŸ‡«πŸ‡·
        • Flight: Base Empreinte πŸ‡«πŸ‡·
        • Flight: CO2 emissiefactoren πŸ‡³πŸ‡±
        • Flight: DEFRA πŸ‡¬πŸ‡§
        • Flight: EPA πŸ‡ΊπŸ‡Έ
        • Flight: GATE4
        • Flight: ICAO
        • Flight: TIM
        • Flight: TU Chalmers πŸ‡ΈπŸ‡ͺ
      • 🏨Hotel
        • Hotel: DEFRA πŸ‡¬πŸ‡§
        • Hotel: HCMI & CHSB
        • Hotel: SQUAKE
      • πŸš†Train
        • Train: ADEME πŸ‡«πŸ‡·
        • Train: Base Empreinte πŸ‡«πŸ‡·
        • Train: CO2-emissiefactoren πŸ‡³πŸ‡±
        • Train: DEFRA πŸ‡¬πŸ‡§
        • Train: SQUAKE
    • πŸ“¦Logistics
      • ✈️Air Freight
        • Air Freight: DIN EN 16258
        • Air Freight: GLEC
      • πŸ›₯️Inland Waterways
        • Inland Waterways: GLEC
      • 🚧Logistics Site
        • Logistics Site: GLEC
      • 🚈Rail Freight
        • Rail Freight: DIN EN 16258
        • Rail Freight: ECTA
        • Rail Freight: GLEC
      • 🚚Road Freight
        • Road Freight: DIN EN 16258
        • Road Freight: GLEC
      • 🚒Sea Freight
        • Road Freight: Clean Cargo
        • Road Freight: DIN EN 16258
        • Road Freight: EMSA πŸ‡ͺπŸ‡Ί
        • Road Freight: GLEC
      • πŸš›Van
        • Van: EEA πŸ‡ͺπŸ‡Ί
  • πŸ†•Notable Changes
    • πŸ“ŠCalculation Changes
      • Events according to HCMI - 2024 updates
      • Train according to CO2 emissiefactoren - energy scope inclusion
      • Train: SQUAKE - April 2025 Update
      • Bus & Train According to DEFRA are Now Available
      • Base Empreinte for Flights and Trains Now Live
      • TIM Transition to Version 2.0
      • TIM & DEFRA: Distance Changes
      • Airline Code Support Update - December 2024
      • GLEC v3.1
      • Car: DEFRA is Now Available
      • Hotel: DEFRA is Now Available
      • Hotel: HCMI - 2024 Updates
      • Accommodation - September 2024 Updates
      • Bus: SQUAKE - September 2024 Update
      • Flight: DEFRA - July 2024 Update
      • GATE4 Methodology is Now Available
      • GLEC, ECTA, and CLEAN-CARGO November 2023 Update
      • Flight: ICAO v13 - July 2024 Update
      • TIM v1.3
      • Train: SQUAKE - August 2024 Update
  • πŸ’‘Use Cases
    • Fulfillment with API
    • Fulfillment with Self-Checkout
    • Webhooks
    • Webhooks API Reference
  • πŸ•΅οΈAudits
    • Retrieve the list of Audit logs
    • Retrieve a specific Audit log
  • πŸ§‘β€πŸ’»Migration Guide
    • From v1 to v2
  • ❓Sustainability FAQs
Powered by GitBook
On this page
  • What are Webhooks?
  • Common Use Cases
  • Implementation Guide
  • Validating incoming webhooks
  • Headers
  • Validation Process
  • Request Body Format
  • Kinds of Webhooks
  • Order webhook
  • Confirmation Document Available
  • Certificate Document Available Webhook
  • Webhook API Reference

Was this helpful?

  1. Use Cases

Webhooks

Using SQUAKE Webhooks API to receive notifications about your customers' purchase-related events

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when events happen in SQUAKE's system. Instead of continuously polling our API, webhooks push data to your endpoint when events occur.

Common Use Cases

  • Payment status notifications

  • Documents status updates (compensation confirmation/certificates are ready)

Implementation Guide

You can setup different webhooks for different kinds of events:

order - we’ll send you an event when purchase which was made via stripe changes status

confirmation_document_available - we’ll send a document when it’s generated

certificate_document_available - we’ll send a document when it’s generated

Validating incoming webhooks

When SQUAKE sends webhooks to your endpoint, we include a signature in the headers that allows you to verify that the request came from us. Here's how to validate the webhooks:

Headers

Each webhook request includes the following security-related headers:

  • HTTP_SQUAKE_SIGNATURE: HMAC-SHA256 signature of the payload

  • HTTP_SQUAKE_TIMESTAMP: ISO8601-formatted timestamp of when the webhook was sent

Validation Process

  1. Get the raw request body as a string

  2. Get the signature from the HTTP_SQUAKE_SIGNATURE header

  3. Calculate the HMAC-SHA256 using your signing key:

# Example in Ruby
payload = request.raw_post  # Get raw request body
signature = OpenSSL::HMAC.hexdigest('SHA256', SIGNING_KEY, payload)

# Compare signatures (use secure comparison)
secure_compare(signature, request.headers['HTTP_SQUAKE_SIGNATURE'])

Request Body Format

The webhook payload is wrapped in a data object:

{
   "data": {
      // ... webhook payload ...
   }
}

Kinds of Webhooks

Order webhook

Type: order

Whenever you request a pricing using /pricing endpoint, it’s possible to pass a payment_method: "stripe" parameter. If it’s passed then we’ll return a paymet_link in the response:

You can add extra query parameters to this link in order to help you to track a specific purchase later, when you receive a webhook. One of the parameters you can pass is: external_reference .

If you’ll add it to the link:

Then we’ll send it back to you in the webhook payload.

Whenever payment is done/cancelled/refunded, we’ll send you a webhook, here’s an example webhook payloads:

{
    "data": {
        "external_reference": "YOUR_EXTERNAL_REFERENCE",
        "purchase_id": "purchase_123456",
        "payment_status": "succeeded"
    }
}

Possible payment_status values:

complete - payment successfully completedcanceled - payment is canceledfailed - payment failed to processsucceeded - payment is successfulrefunded - payment is refunded

Confirmation Document Available

Type: confirmation_document_available

Notifies you when a compensation confirmation document is ready for download.

Payload

{
  "data": {
    "id": "file_XXX-XXX-XXX-XXX-XXX",
    "filename": "SQUAKE-CompensationCertificate-euc1XXX.pdf",
    "purpose": "confirmation_document",
    "size": 100,
    "type": "pdf",
    "download_url": "https://squake.s3.eu-central-1.amazonaws.com/...."
  }
}

Certificate Document Available Webhook

Type: certificate_document_available

Notifies you when a certificate document is ready for download.

Payload

{
  "data": {
    "id": "file_XXX-XXX-XXX-XXX-XXX",
    "filename": "SQUAKE-CompensationCertificate-euc1XXX.pdf",
    "purpose": "certificate_document",
    "size": 100,
    "type": "pdf",
    "download_url": "https://squake.s3.eu-central-1.amazonaws.com/...."
  }
}

Webhook API Reference

PreviousFulfillment with Self-CheckoutNextWebhooks API Reference

Last updated 1 day ago

Was this helpful?

&external_reference=YOUR_EXTERNAL_REFERENCE

See for more details.

πŸ’‘
https://checkout.squake.test?t=eyJhbGciOiJIUzI1NiJ9.eyJwIjoicHJpY2VfZFJTbmtVIiwiY3EiOjEuMCwiY3UiOiJ0b25uZSIsInQiOjEyMzMxLCJ0ZSI6MTIzMzEsImwiOiJlbiIsImMiOiJFVVIiLCJleHAiOjE3MzU4MTUzMTIsImZ0IjowLCJwbSI6InN0cmlwZSJ9.xO4V8-l4aPPJOAFYIjbUCiYRKbzyUZJYbf3j-umV-8A
https://checkout.squake.test?t=eyJhbGciOiJIUzI1NiJ9.eyJwIjoicHJpY2VfZFJTbmtVIiwiY3EiOjEuMCwiY3UiOiJ0b25uZSIsInQiOjEyMzMxLCJ0ZSI6MTIzMzEsImwiOiJlbiIsImMiOiJFVVIiLCJleHAiOjE3MzU4MTUzMTIsImZ0IjowLCJwbSI6InN0cmlwZSJ9.xO4V8-l4aPPJOAFYIjbUCiYRKbzyUZJYbf3j-umV-8A
Webhook API Reference