# Webhooks

## 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:

```ruby
# 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

```json
{
  // ... 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:

[https://checkout.squake.test?t=eyJhbGciOiJIUzI1NiJ9.eyJwIjoicHJpY2VfZFJTbmtVIiwiY3EiOjEuMCwiY3UiOiJ0b25uZSIsInQiOjEyMzMxLCJ0ZSI6MTIzMzEsImwiOiJlbiIsImMiOiJFVVIiLCJleHAiOjE3MzU4MTUzMTIsImZ0IjowLCJwbSI6InN0cmlwZSJ9.xO4V8-l4aPPJOAFYIjbUCiYRKbzyUZJYbf3j-umV-8A](https://checkout.squake.cloud/?t=eyJhbGciOiJIUzI1NiJ9.eyJwIjoicHJpY2VfZFJTbmtVIiwiY3EiOjEuMCwiY3UiOiJ0b25uZSIsInQiOjEyMzMxLCJ0ZSI6MTIzMzEsImwiOiJlbiIsImMiOiJFVVIiLCJleHAiOjE3MzU4MTUzMTIsImZ0IjowLCJwbSI6InN0cmlwZSJ9.xO4V8-l4aPPJOAFYIjbUCiYRKbzyUZJYbf3j-umV-8A)

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:

[https://checkout.squake.test?t=eyJhbGciOiJIUzI1NiJ9.eyJwIjoicHJpY2VfZFJTbmtVIiwiY3EiOjEuMCwiY3UiOiJ0b25uZSIsInQiOjEyMzMxLCJ0ZSI6MTIzMzEsImwiOiJlbiIsImMiOiJFVVIiLCJleHAiOjE3MzU4MTUzMTIsImZ0IjowLCJwbSI6InN0cmlwZSJ9.xO4V8-l4aPPJOAFYIjbUCiYRKbzyUZJYbf3j-umV-8A](https://checkout.squake.cloud/?t=eyJhbGciOiJIUzI1NiJ9.eyJwIjoicHJpY2VfZFJTbmtVIiwiY3EiOjEuMCwiY3UiOiJ0b25uZSIsInQiOjEyMzMxLCJ0ZSI6MTIzMzEsImwiOiJlbiIsImMiOiJFVVIiLCJleHAiOjE3MzU4MTUzMTIsImZ0IjowLCJwbSI6InN0cmlwZSJ9.xO4V8-l4aPPJOAFYIjbUCiYRKbzyUZJYbf3j-umV-8A)**\&external\_reference=YOUR\_EXTERNAL\_REFERENCE**

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:

```json
{
  "external_reference": "YOUR_EXTERNAL_REFERENCE",
  "purchase_id": "purchase_123456",
  "payment_status": "succeeded"
}
```

Possible `payment_status` values:

`complete` - payment successfully completed `canceled` - payment is canceled `failed` - payment failed to process `succeeded` - payment is successful `refunded` - payment is refunded

### Confirmation Document Available

**Type:** `confirmation_document_available`

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

#### Payload

```json
{
 "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

```json
{
  "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

See [Webhook API Reference](https://docs-integration.squake.earth/use-cases/webhooks-api-reference) for more details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-integration.squake.earth/use-cases/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.