Creating Event Types

Define the types of events your application will send to webhook subscribers.

---

What are Event Types?

Event Types define the structure and purpose of the webhooks you send from your application. Each event type represents a specific occurrence in your system that subscribers can listen to.

Examples:

• user.created - When a new user registers
• order.shipped - When an order is dispatched
• payment.completed - When a payment succeeds
• subscription.cancelled - When a subscription ends

---

Event Types Page

View and manage all your event types in one place.

Key Features

Centralized Management: All event types in one view
Status Control: Enable/disable event types
Search & Filter: Find specific event types quickly
Quick Actions: Edit or delete event types
Pagination: Navigate through large lists

---

Event Type Columns

NAME

The unique identifier for your event type.

Naming Convention: Use dot notation for clarity

resource.action

Examples:

• order.shipped
• user.created
• payment.completed
• invoice.updated

Best Practices:

• Use lowercase
• Use dots to separate resource and action
• Be descriptive and specific
• Keep it concise

DESCRIPTION

Human-readable explanation of when this event is triggered.

Examples:

Triggered when the order is shipped
Triggered when a new user is created
Triggered when payment is completed
Triggered when subscription is cancelled

Best Practices:

• Start with "Triggered when..."
• Be clear and concise
• Explain the exact condition
• Help developers understand the event

STATUS

Indicates whether the event type is active.

Enabled (Green badge):

• Event type is active
• Events can be sent
• Subscribers will receive events

Disabled (Gray badge):

• Event type is inactive
• Events cannot be sent
• Subscribers won't receive events

Use Cases:

• Temporarily pause events
• Deprecate old event types
• Test before enabling

CREATED

Timestamp when the event type was created.

Format: YYYY-MM-DD HH:MM:SS

Example: 2025-12-24 16:00:54

ACTIONS

Quick actions for each event type.

Edit (Pencil icon):

• Modify event type details
• Update description
• Change status

Delete (Trash icon):

• Remove event type
• Cannot be undone
• Only if no active subscriptions

---

Filtering Event Types

Use filters to find specific event types quickly.

Filter by Status

Dropdown: "Enabled"

Options:

• All
• Enabled
• Disabled

Use Case: View only active or inactive event types

Search by Name

Search Box: "Search by name..."

Type to search for event types by name.

Examples:

• Search "order" to find all order-related events
• Search "user" to find all user-related events
• Search "payment" to find all payment-related events

Reset Filters

Reset Button: Clear all filters and show all event types

---

Creating an Event Type

Step 1: Click Create Event Type

Click the "+ Create Event Type" button in the top right.

Step 2: Configure Basic Details

Name (Required):

user.created

Description (Optional):

Triggered when a new user is created

Status:

• ☑ Enabled (default)
• ☐ Disabled

Step 3: Define Event Schema (Optional)

Define the structure of your event payload using JSON Schema.

Example Schema:

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Unique user identifier"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "User email address"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "User creation timestamp"
    },
    "plan": {
      "type": "string",
      "enum": ["free", "pro", "enterprise"],
      "description": "User subscription plan"
    }
  },
  "required": ["user_id", "email", "created_at"]
}

Step 4: Save Event Type

Click "Create Event Type" to save.

---

Event Type Examples

User Events

user.created

Description: Triggered when a new user is created
Schema: user_id, email, created_at, plan

user.updated

Description: Triggered when user profile is updated
Schema: user_id, updated_fields, updated_at

user.deleted

Description: Triggered when a user account is deleted
Schema: user_id, deleted_at, reason

Order Events

order.created

Description: Triggered when a new order is placed
Schema: order_id, customer_id, items, total_amount, created_at

order.shipped

Description: Triggered when the order is shipped
Schema: order_id, tracking_number, carrier, shipped_at

order.delivered

Description: Triggered when the order is delivered
Schema: order_id, delivered_at, signature

Payment Events

payment.completed

Description: Triggered when payment is completed
Schema: payment_id, amount, currency, customer_id, completed_at

payment.failed

Description: Triggered when payment fails
Schema: payment_id, amount, currency, failure_reason, failed_at

payment.refunded

Description: Triggered when payment is refunded
Schema: payment_id, refund_amount, refund_reason, refunded_at

Subscription Events

subscription.started

Description: Triggered when a new subscription starts
Schema: subscription_id, customer_id, plan, started_at

subscription.renewed

Description: Triggered when subscription renews
Schema: subscription_id, renewal_date, next_billing_date

subscription.cancelled

Description: Triggered when subscription is cancelled
Schema: subscription_id, cancelled_at, cancellation_reason

---

Event Naming Best Practices

Use Consistent Patterns

Resource.Action Format:

user.created
order.shipped
payment.completed
subscription.cancelled

Past Tense for Completed Actions: ✅ order.shipped (action completed)
✅ payment.completed (action completed)
❌ order.shipping (action in progress)
❌ payment.completing (action in progress)

Be Specific

Good:

order.shipped
order.delivered
order.cancelled

Bad:

order.updated (too vague)
order.changed (too vague)
order.event (meaningless)

Group Related Events

User Lifecycle:

user.created
user.updated
user.deleted
user.suspended
user.reactivated

Order Lifecycle:

order.created
order.paid
order.shipped
order.delivered
order.cancelled
order.refunded

---

Event Schema Design

Basic Schema Structure

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "Event timestamp"
    }
  },
  "required": ["id", "timestamp"]
}

Include Metadata

{
  "type": "object",
  "properties": {
    "event_id": {"type": "string"},
    "event_type": {"type": "string"},
    "occurred_at": {"type": "string", "format": "date-time"},
    "version": {"type": "string"},
    "data": {
      "type": "object",
      "properties": {
        "user_id": {"type": "string"},
        "email": {"type": "string"}
      }
    }
  },
  "required": ["event_id", "event_type", "occurred_at", "data"]
}

Use Enums for Fixed Values

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "processing", "completed", "failed"],
      "description": "Order status"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "urgent"],
      "description": "Order priority"
    }
  }
}

Version Your Schemas

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string",
      "enum": ["v1", "v2"],
      "description": "Schema version"
    },
    "data": {
      "type": "object"
    }
  },
  "required": ["schema_version", "data"]
}

---

Managing Event Types

Editing Event Types

1. Click Edit Icon: In the Actions column
2. Update Details: Modify name, description, or schema
3. Save Changes: Click "Save" to apply

Note: Changing event type name may affect existing subscriptions

Disabling Event Types

1. Click Edit Icon: Open event type details
2. Toggle Status: Change from Enabled to Disabled
3. Save: Confirm changes

Effect:

• New events cannot be sent
• Existing subscriptions remain
• Can be re-enabled anytime

Deleting Event Types

1. Click Delete Icon: In the Actions column
2. Confirm Deletion: Confirm you want to delete
3. Event Type Removed: Cannot be undone

Requirements:

• No active subscriptions
• No pending events
• Cannot be recovered after deletion

---

Pagination

Navigate through event types efficiently.

Display: "Page 1 of 1 - Showing 2 of 2 event types"

Controls:

• Previous: Go to previous page
• Next: Go to next page
• Page indicator

---

Common Use Cases

E-commerce Platform

Event Types:

order.created
order.paid
order.shipped
order.delivered
order.cancelled
order.refunded
inventory.low_stock
inventory.out_of_stock
customer.registered
customer.verified

SaaS Application

Event Types:

user.signed_up
user.activated
user.deactivated
subscription.started
subscription.upgraded
subscription.downgraded
subscription.cancelled
usage.limit_reached
invoice.generated
invoice.paid

Payment Platform

Event Types:

payment.initiated
payment.processing
payment.completed
payment.failed
payment.refunded
payout.scheduled
payout.completed
payout.failed
dispute.created
dispute.resolved

---

Best Practices

Event Design

✅ Use Clear Names: order.shipped not ord_shp
✅ Be Consistent: Follow same naming pattern
✅ Add Descriptions: Help developers understand
✅ Version Schemas: Plan for future changes

Organization

✅ Group by Resource: All user events together
✅ Logical Ordering: Follow lifecycle order
✅ Document Events: Maintain event catalog
✅ Review Regularly: Remove unused events

Schema Design

✅ Include Timestamps: Always add event time
✅ Use Required Fields: Mark essential fields
✅ Add Descriptions: Document each field
✅ Validate Data: Use appropriate types

Maintenance

✅ Monitor Usage: Track which events are used
✅ Deprecate Gracefully: Give notice before removing
✅ Version Changes: Don't break existing integrations
✅ Document Changes: Keep changelog updated

---

Troubleshooting

Cannot Create Event Type

Possible Causes:

• Event type name already exists
• Invalid name format
• Missing required fields

Solutions:

1. Choose unique event type name
2. Use valid naming convention (lowercase, dots)
3. Fill all required fields

Cannot Delete Event Type

Possible Causes:

• Active subscriptions exist
• Pending events in queue

Solutions:

1. Remove all subscriptions first
2. Wait for pending events to complete
3. Then delete event type

Events Not Being Sent

Possible Causes:

• Event type is disabled
• No active subscriptions
• Invalid event data

Solutions:

1. Enable event type
2. Create subscriptions
3. Validate event payload against schema

---

Next Steps

• Managing Subscriptions - Create webhook subscriptions
• Sending Events - Send events via API/SDK
• Monitoring Deliveries - Track event delivery

---

Ready to send webhooks? Create your first event type and start notifying subscribers! 🚀