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.com/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:

1. Extract the timestamp and signature from the X-Webhook-Signature header:

   t=1234567890,v1=signature

2. Concatenate the timestamp and request body:

   timestamp + "." + request_body

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

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

4. 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

1. Verify Signatures: Always verify webhook signatures to ensure requests are legitimate.

2. Handle Duplicates: Implement idempotency checks using the webhook ID.

3. Quick Response: Respond with a 2xx status code quickly (within 5 seconds).

4. Retry Handling: Be prepared for retry attempts if your endpoint is temporarily unavailable.

5. Error Handling: Return appropriate HTTP status codes:

   • 2xx: Success
   • 4xx: Client error (will not be retried)
   • 5xx: Server error (will be retried)

6. Logging: Log webhook requests and responses for debugging.

7. Testing: Use the test endpoint to verify your webhook implementation.

8. 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)