Webhook Management

Configure Webhooks in Settings

Access webhook configuration

Set up webhook notifications:

• Settings: Navigate to Settings in Pulse Billing
• Webhooks tab: Open the Webhooks tab
• Add Webhook: Click the "+ Add Webhook" button to create new webhook endpoints
• Webhook Table: View all existing webhooks with their names, URLs, and management options

Create a new webhook endpoint

Set up webhook notifications:

• Webhook Name: Enter a descriptive name for your webhook (e.g., "customer_web_hook")
• Webhook URL: Provide the full endpoint URL where notifications will be sent
• URL Format: Use complete URLs like http://localhost:9797/TestWebhookUrl/ or your production endpoint
• Save Configuration: Add the webhook to your account settings

Manage existing webhooks

Update or remove webhooks:

• View All Webhooks: See all configured webhooks in the webhook table
• Webhook Details: Each webhook shows Name, URL, and available actions
• Delete Webhook: Use the trash icon to remove webhooks you no longer need
• Update URLs: Modify webhook endpoints as needed for your integration

Understand Webhook Events

Supported event types

Webhooks trigger for these events:

• NewOrder: When a customer completes a one-time purchase
• NewSubscription: When a customer starts a new subscription
• SubscriptionRenewal: When an existing subscription renews
• SubscriptionCancellation: When a customer cancels their subscription
• Refund: When a refund is processed for an order

Webhook payload structure

Each webhook sends this data:

• ProductId: The ID of the product that was purchased
• OrderId: The unique order item ID
• TransactionId: The payment transaction ID
• EventType: The type of event that triggered the webhook
• ContactPerson: Customer information including:
  • FirstName: Customer's first name
  • LastName: Customer's last name
  • Email: Customer's email address
• Address: Customer billing address including:
  • Line1: Primary address line
  • Line2: Secondary address line (apartment, suite, etc.)
  • City: Customer's city
  • State: Customer's state or province
  • PostalCode: ZIP code or postal code
  • Country: Full country name

Implement Webhook Endpoints

Webhook Endpoint Requirements

Your webhook endpoint must meet these specifications:

• HTTP Method: POST
• Content-Type: application/json
• Response Time: Under 30 seconds
• Status Codes: Return appropriate HTTP status codes

Webhook Payload Format

Pulse Billing sends webhook notifications using the following JSON structure:

{
  "ProductId": 123,
  "OrderId": 456,
  "TransactionId": 789,
  "EventType": "NewOrder",
  "ContactPerson": {
    "FirstName": "John",
    "LastName": "Doe",
    "Email": "[email protected]"
  },
  "Address": {
    "Line1": "123 Main Street",
    "Line2": "Apt 4B",
    "City": "New York",
    "State": "NY",
    "PostalCode": "10001",
    "Country": "United States"
  }
}

Payload Parameters

Parameter	Type	Required	Description
ProductId	integer	Yes	The ID of the product that was purchased
OrderId	integer	Yes	The unique order item ID
TransactionId	integer	Yes	The payment transaction ID
EventType	string	Yes	The type of event that triggered the webhook
ContactPerson	object	Yes	Customer contact information
ContactPerson.FirstName	string	Yes	Customer's first name
ContactPerson.LastName	string	Yes	Customer's last name
ContactPerson.Email	string	Yes	Customer's email address
Address	object	Yes	Customer billing address information
Address.Line1	string	Yes	Primary address line
Address.Line2	string	No	Secondary address line (apartment, suite, etc.)
Address.City	string	Yes	Customer's city
Address.State	string	Yes	Customer's state or province
Address.PostalCode	string	Yes	ZIP code or postal code
Address.Country	string	Yes	Full country name

Event Type Values

Event Type	Description	Triggered When
NewOrder	New one-time purchase completed	Customer completes a one-time purchase
NewSubscription	New subscription started	Customer starts their first subscription period
SubscriptionRenewal	Subscription renewed	Existing subscription renews for another period
SubscriptionCancellation	Subscription cancelled	Customer cancels their subscription
Refund	Payment refunded	A refund is processed for an order

Response Requirements

Your webhook endpoint should return:

Success Response (200 OK)

{
  "status": "success",
  "message": "Webhook processed successfully"
}

Error Response (4xx/5xx)

{
  "status": "error",
  "message": "Error processing webhook"
}

HTTP Status Codes

Status Code	Description	Action Required
200	Success	Webhook processed successfully
400	Bad Request	Fix payload validation issues
401	Unauthorized	Check authentication
404	Not Found	Verify endpoint URL
500	Internal Server Error	Check server logs and retry

---

Ready to integrate webhooks? Set up webhook endpoints in Settings → Webhooks to receive real-time notifications about customer orders, subscriptions, and payments.