Webhooks API Documentation

Overview

Our webhook system allows you to receive real-time notifications about events in your application. Each webhook delivery includes a signature for security verification and follows a consistent payload format.

Base URL

https://api.scute.io/v1

Authentication

All webhook endpoints require authentication using your API key. Include it in the request header:

Authorization: Bearer YOUR_API_KEY

Creating a Webhook Endpoint

Request

POST /apps/{app_id}/webhooks
Content-Type: application/json

{
  "webhook": {
    "url": "https://your-domain.com/webhooks",
    "description": "Production webhook endpoint",
    "enabled": true,
    "event_types": ["user.created", "user.updated"],
    "retry_limit": 3,
    "metadata": {
      "environment": "production",
      "team": "backend"
    }
  }
}

Parameters

Parameter	Type	Required	Description
url	string	Yes	The URL where webhooks will be sent
description	string	No	A description of the webhook endpoint
enabled	boolean	No	Whether the endpoint is active (default: true)
event_types	array	No	Array of event types to subscribe to (default: [”*”])
retry_limit	integer	No	Number of retry attempts (0-10, default: 3)
metadata	object	No	Custom metadata for the webhook endpoint

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://your-domain.com/webhooks",
  "description": "Production webhook endpoint",
  "enabled": true,
  "event_types": ["user.created", "user.updated"],
  "retry_limit": 3,
  "version": "v1",
  "metadata": {
    "environment": "production",
    "team": "backend"
  },
  "last_ping_at": "2024-03-21T12:00:00Z",
  "created_at": "2024-03-21T12:00:00Z",
  "updated_at": "2024-03-21T12:00:00Z"
}

Webhook Payload Format

Headers

Each webhook request includes the following headers:

Content-Type: application/json
User-Agent: AppName-Webhooks/1.0
X-Webhook-Signature: t=1234567890,v1=signature

Payload Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-03-21T12:00:00Z",
  "event_type": "user.created",
  "app_id": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    // Event-specific data
  },
  "metadata": {
    // Event metadata if required
  },
  "context": {
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "controller": "UsersController",
    "params": {
      // Request parameters
    }
  },
  "api_version": "v1"
}

Event Categories

Events are automatically categorized based on their type:

Category	Description	Event Types
auth	Authentication related events	`auth.*`
user	User management events	`user.*`
token	Token management events	`token.*`
verification	Verification related events	`verification.*`
system	System level events	`webhook.test` and others

Required Metadata

Certain events require metadata to be included:

Event Type	Required Metadata
auth.login.failed	Error details
auth.verification.failed	Verification failure reason
user.verification.failed	User verification details

Verifying Webhook Signatures

To verify the authenticity of webhook requests, you should validate the signature. Here’s how:

Extract the timestamp and signature from the X-Webhook-Signature header:
```
t=1234567890,v1=signature
```
Concatenate the timestamp and request body:
```
timestamp + "." + request_body
```

Generate an HMAC SHA-256 signature using your webhook secret:

signature = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new("sha256"),
  webhook_secret,
  "#{timestamp}.#{request_body}"
)

Compare the generated signature with the one in the header.

Event Types

Authentication Events

auth.login.failed
auth.verification.failed

User Events

user.created
user.updated
user.verification.failed

Token Events

token.refreshed
token.verified

Verification Events

verification.attempted
verification.failed

System Events

webhook.test

Managing Webhook Endpoints

List Endpoints

GET /apps/{app_id}/webhooks

Get Endpoint Details

GET /apps/{app_id}/webhooks/{webhook_id}

Update Endpoint

PATCH /apps/{app_id}/webhooks/{webhook_id}
Content-Type: application/json

{
  "webhook": {
    "description": "Updated description",
    "enabled": false,
    "metadata": {
      "environment": "staging"
    }
  }
}

Delete Endpoint

DELETE /apps/{app_id}/webhooks/{webhook_id}

Test Endpoint

POST /apps/{app_id}/webhooks/{webhook_id}/test

View Delivery History

GET /apps/{app_id}/webhooks/{webhook_id}/deliveries?page=1

Response:

{
  "deliveries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "delivered",
      "response_code": 200,
      "response_body": "OK",
      "error_message": null,
      "retry_count": 0,
      "delivered_at": "2024-03-21T12:00:00Z",
      "created_at": "2024-03-21T12:00:00Z",
      "updated_at": "2024-03-21T12:00:00Z",
      "event": {
        // Event details
      }
    }
  ],
  "meta": {
    "total_count": 100,
    "total_pages": 4,
    "current_page": 1
  }
}

Delivery Status

Webhook deliveries can have the following statuses:

Status	Description
pending	Initial state, waiting to be processed
processing	Currently being delivered
delivered	Successfully delivered to the endpoint
failed	Delivery failed (will be retried if retryable)

Best Practices

Verify Signatures: Always verify webhook signatures to ensure requests are legitimate.
Handle Duplicates: Implement idempotency checks using the webhook ID.
Quick Response: Respond with a 2xx status code quickly (within 5 seconds).
Retry Handling: Be prepared for retry attempts if your endpoint is temporarily unavailable.
Error Handling: Return appropriate HTTP status codes:
- 2xx: Success
- 4xx: Client error (will not be retried)
- 5xx: Server error (will be retried)
Logging: Log webhook requests and responses for debugging.
Testing: Use the test endpoint to verify your webhook implementation.
Metadata: Include relevant metadata for events that require it.

Rate Limits and Timeouts

Maximum 10 retry attempts per delivery
Maximum 3 concurrent deliveries per endpoint
10-second timeout for each delivery attempt
Background job retries with exponential backoff (max 5 attempts)

Getting Started

Quickstarts

Guides

Verification

Webhooks

Webhooks API Documentation

Overview

Base URL

Authentication

Creating a Webhook Endpoint

Request

Parameters

Response

Webhook Payload Format

Headers

Payload Structure

Event Categories

Required Metadata

Verifying Webhook Signatures

Event Types

Authentication Events

User Events

Token Events

Verification Events

System Events

Managing Webhook Endpoints

List Endpoints

Get Endpoint Details

Update Endpoint

Delete Endpoint

Test Endpoint

View Delivery History

Delivery Status

Best Practices

Rate Limits and Timeouts

Getting Started

Quickstarts

Guides

Verification

​Webhooks API Documentation

​Overview

​Base URL

​Authentication

​Creating a Webhook Endpoint

​Request

​Parameters

​Response

​Webhook Payload Format

​Headers

​Payload Structure

​Event Categories

​Required Metadata

​Verifying Webhook Signatures

​Event Types

​Authentication Events

​User Events

​Token Events

​Verification Events

​System Events

​Managing Webhook Endpoints

​List Endpoints

​Get Endpoint Details

​Update Endpoint

​Delete Endpoint

​Test Endpoint

​View Delivery History

​Delivery Status

​Best Practices

​Rate Limits and Timeouts

Webhooks API Documentation

Overview

Base URL

Authentication

Creating a Webhook Endpoint

Request

Parameters

Response

Webhook Payload Format

Headers

Payload Structure

Event Categories

Required Metadata

Verifying Webhook Signatures

Event Types

Authentication Events

User Events

Token Events

Verification Events

System Events

Managing Webhook Endpoints

List Endpoints

Get Endpoint Details

Update Endpoint

Delete Endpoint

Test Endpoint

View Delivery History

Delivery Status

Best Practices

Rate Limits and Timeouts