Skip to main content
Version: 1.0.0

hookVM API

The hookVM API enables you to send events from your application to webhook subscriptions, manage event types, and configure webhook endpoints programmatically.

Getting Started​

  1. Obtain an API Key: Generate an API key from your hookVM dashboard
  2. Create Event Types: Define the types of events your application will send
  3. Create Subscriptions: Set up webhook endpoints to receive events
  4. Send Events: Trigger events that will be delivered to all active subscriptions

Authentication​

All API requests require authentication using an API key. Include your API key in the X-Api-Key header:

X-Api-Key: sk_live_1234567890abcdef

Security Best Practices:

  • Never expose your API key in client-side code
  • Use environment variables to store API keys
  • Rotate API keys regularly
  • Use different API keys for development and production

Rate Limiting​

All API requests are rate limited on a per-organization basis to ensure fair usage and system stability.

Rate Limit Details:

  • Default Limit: 100 requests per minute per organization
  • Plan-Based: Your rate limit may vary based on your subscription plan
  • Scope: Rate limits are applied per organization, not per API key
  • Window: 1 minute rolling window

Rate Limit Headers:

Every API response includes the following headers to help you track your usage:

  • X-RateLimit-Limit: Maximum number of requests allowed per minute
  • X-RateLimit-Remaining: Number of requests remaining in the current window
  • X-RateLimit-Reset: Seconds until the rate limit resets

Example Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 45

Rate Limit Exceeded:

When you exceed your rate limit, you'll receive a 429 Too Many Requests response with additional headers:

  • Retry-After: Seconds to wait before retrying the request

Best Practices:

  • Monitor the X-RateLimit-Remaining header to track your usage
  • Implement exponential backoff when receiving 429 responses
  • Cache responses when possible to reduce API calls
  • Distribute requests evenly throughout the minute window

Idempotency​

To prevent duplicate event processing, use the optional idempotencyKey field when sending events. If you retry a request with the same idempotency key within 24 hours, you'll receive the original response without creating a duplicate event.

Example:

{
  "eventType": "user.created",
  "payload": {"userId": "123"},
  "idempotencyKey": "user-123-created-20240115"
}

Error Handling​

The API uses standard HTTP status codes and returns detailed error messages in JSON format:

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 204 No Content: Resource deleted successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing API key
  • 404 Not Found: Resource not found
  • 409 Conflict: Duplicate resource (e.g., idempotency key already used)
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Webhook Signatures​

All webhook deliveries include a signature in the X-Webhook-Signature header for verification. Use the subscription's signature secret to verify the authenticity of webhook payloads.

Support​

Authentication​

API key for authentication. Generate API keys from your hookVM dashboard at https://app.hookvm.com/settings/api-keys

Security Scheme Type:

apiKey

Header parameter name:

X-Api-Key

Terms of Service

https://hookvm.com/terms