Webhook Template Overview

​

What Are Webhook Templates?

• HTTP method and path for the target endpoint
• Request body, headers, and query parameters (with support for dynamic variables)
• Retry logic (delay, backoff mode, max retries)
• Timeout settings
• Domain association for rate limiting and concurrency control

​

Key Benefits

​

1. Reusability

Template: "Send Order Notification"
UUID: abc-123-def-456

Use in:
- Order creation workflow
- Order update workflow  
- Order cancellation workflow

​

2. Consistency

​

3. Easy Updates

​

4. Developer-Friendly

​

5. Visual Management

​

Template Variables

​

System Secret Vault Variables

{{ #key }}

• The # symbol indicates this is a system secret
• key is the name of the secret stored in your vault
• Secrets are computed at runtime when the webhook is executed
• Values are never exposed in logs or responses

{
  "headers_json": {
    "Authorization": "Bearer {{ #api_key }}",
    "X-API-Key": "{{ #service_api_key }}"
  }
}

​

Workflow Variables

{{ variable }}

• variable can be any variable name from your workflow context
• Values are injected at runtime from your workflow execution
• Supports nested properties (e.g., {{ user.email }})

{
  "request_body_json": {
    "user_id": "{{ user_id }}",
    "order_id": "{{ order_id }}",
    "email": "{{ customer_email }}"
  }
}

​

Variable Usage Locations

• Request Body (request_body_json): Any field value
• Headers (headers_json): Header values
• Query Parameters (query_params_json): Query parameter values
• URL Path (path): Dynamic path segments

{
  "method": "POST",
  "path": "/api/users/{{ user_id }}/notifications",
  "request_body_json": {
    "message": "Hello {{ user_name }}",
    "order_id": "{{ order_id }}"
  },
  "headers_json": {
    "Authorization": "Bearer {{ #api_key }}",
    "X-User-ID": "{{ user_id }}"
  },
  "query_params_json": {
    "timestamp": "{{ created_at }}",
    "source": "{{ source }}"
  }
}

​

Creating Templates

​

Option 1: Dashboard (Visual Tools)

1. Navigate to the Webhooks tab in your dashboard
2. Click Create Template or Add Template
3. Fill in the form fields:
   • Webhook name and description
   • HTTP method and path
   • Request body, headers, and query parameters
   • Retry settings and timeout
   • Domain selection
4. Use the visual editor to add template variables
5. Save the template and get the webhook-uuid

• No coding required
• Visual validation
• Easy testing
• Quick iteration

​

Option 2: API

curl -X POST https://api.hookpulse.io/v1/api/add_webhook_template/ \
  -H "x-hookpulse-api-key: YOUR_API_KEY" \
  -H "x-brand-uuid: YOUR_BRAND_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_name": "Order Notification",
    "method": "POST",
    "path": "/api/orders/{{ order_id }}",
    "domain_uuid": "your-domain-uuid",
    "request_body_json": {
      "order_id": "{{ order_id }}",
      "status": "{{ status }}"
    },
    "headers_json": {
      "Authorization": "Bearer {{ #api_key }}"
    }
  }'

• Automation-friendly
• Version control integration
• CI/CD pipeline support
• Bulk template creation

​

Using Templates

{
  "webhook_uuid": "abc-123-def-456",
  "variables": {
    "order_id": "12345",
    "user_id": "67890",
    "status": "completed"
  }
}

1. Retrieve the template configuration
2. Substitute all template variables with actual values
3. Compute system secrets from the vault
4. Execute the webhook with retry logic and timeout handling

​

Retry Logic

• Retry Delay: Time to wait between retry attempts (in seconds)
• Retry Backoff Mode:
  • linear: Fixed delay between retries
  • exponential: Increasing delay between retries
• Max Retries: Maximum number of retry attempts
• Request Timeout: Maximum time to wait for a response (in milliseconds)

​

Domain Association

• Rate Limiting: Controls requests per second
• Concurrency Control: Limits simultaneous requests
• Consistent Configuration: All templates for a domain share the same rate/concurrency settings

​

Best Practices

1. Use Descriptive Names: Choose clear template names (e.g., “Send Order Confirmation Email”)
2. Document Variables: Include descriptions of required variables in the template description
3. Test Templates: Validate templates in staging before production use
4. Version Control: Keep track of template changes, especially when using APIs
5. Secure Secrets: Always use {{ #key }} syntax for sensitive values, never hardcode
6. Optimize Retries: Set appropriate retry delays and max retries based on your endpoint’s reliability
7. Monitor Performance: Track success rates and adjust timeout/retry settings accordingly

​

Example Use Cases

​

E-commerce Order Processing

{
  "webhook_name": "Order Created Notification",
  "path": "/api/orders/{{ order_id }}",
  "request_body_json": {
    "order_id": "{{ order_id }}",
    "customer_email": "{{ customer_email }}",
    "total_amount": "{{ total_amount }}"
  },
  "headers_json": {
    "Authorization": "Bearer {{ #ecommerce_api_key }}"
  }
}

​

User Authentication Webhooks

{
  "webhook_name": "User Login Notification",
  "path": "/auth/webhooks/login",
  "request_body_json": {
    "user_id": "{{ user_id }}",
    "login_time": "{{ timestamp }}",
    "ip_address": "{{ ip_address }}"
  },
  "headers_json": {
    "X-API-Key": "{{ #auth_service_key }}"
  }
}

​

Payment Processing

{
  "webhook_name": "Payment Status Update",
  "path": "/payments/{{ payment_id }}/status",
  "request_body_json": {
    "payment_id": "{{ payment_id }}",
    "status": "{{ payment_status }}",
    "amount": "{{ amount }}"
  },
  "headers_json": {
    "Authorization": "Bearer {{ #payment_api_key }}",
    "X-Merchant-ID": "{{ merchant_id }}"
  }
}

​

Related APIs

• Add Webhook Template - Create a new webhook template via API

​

Related Documentation

• System Secret Vault Overview - Learn about storing and using secrets
• Domain Setup Overview - Configure rate limiting and concurrency control