Webhooks API Guide

Listen to real-time events in your gigstack account. The Webhooks API allows you to configure endpoints that receive event notifications when specific actions occur in your system.

📋 Overview

Webhooks enable you to build event-driven integrations by receiving automatic HTTP POST notifications when events occur in your gigstack account. Configure which events to listen for and where to receive them.

🔑 Key Features

Real-time Notifications - Instant event delivery to your endpoints

Event Filtering - Subscribe only to events you need

Status Control - Enable/disable webhooks without deletion

Multi-event Support - Single webhook can listen to multiple event types

Secure Delivery - HTTPS endpoint requirement for production

📚 Endpoints

List Webhooks

Retrieve all configured webhooks for your team.

Query Parameters:

limit (integer, 1-100) - Number of results to return (default: 10)

status (string) - Filter by status: active or inactive

team (string) - gigstack Connect: Target team ID

Example Request:

Example Response:

{
    "success": true,
    "message": "Webhooks retrieved successfully",
    "data": [
        {
            "id": "wh_dyS2ZVTj",
            "url": "https://webhook.site/7cd05529-40fe-4c98-88e5-761de9c5feb1",
            "events": [
                "payment.created",
                "payment.succeeded",
                "invoice.created"
            ],
            "status": "active",
            "description": "Production payment notifications",
            "owner": "8UWdgXELUhf022vuoq249mtGytG2",
            "created_at": 1709090576567
        }
    ],
    "timestamp": 1709090576567
}

Get Webhook

Retrieve details of a specific webhook.

Example Request:

Example Response:

{
    "success": true,
    "message": "Webhook retrieved successfully",
    "data": {
        "id": "wh_dyS2ZVTj",
        "url": "https://webhook.site/7cd05529-40fe-4c98-88e5-761de9c5feb1",
        "events": [
            "payment.created",
            "payment.succeeded",
            "invoice.created"
        ],
        "status": "active",
        "description": "Production payment notifications",
        "owner": "8UWdgXELUhf022vuoq249mtGytG2",
        "created_at": 1709090576567
    },
    "timestamp": 1709090576567
}

Create Webhook

Create a new webhook endpoint to receive event notifications.

Request Body:

{
    "url": "https://your-domain.com/webhooks/gigstack",
    "events": [
        "payment.created",
        "payment.succeeded",
        "invoice.created"
    ],
    "description": "Production webhook for payment events",
    "status": "active"
}

Required Fields:

url (string) - HTTPS endpoint URL to receive webhook events

events (array) - List of event types to subscribe to (see Available Events below)

Optional Fields:

description (string) - Human-readable description of the webhook

status (string) - active or inactive (default: active)

Example Request:

Example Response:

{
    "success": true,
    "message": "Webhook created successfully",
    "data": {
        "id": "wh_dyS2ZVTj",
        "url": "https://your-domain.com/webhooks/gigstack",
        "events": ["payment.created", "payment.succeeded"],
        "status": "active",
        "description": "Payment notifications webhook",
        "owner": "8UWdgXELUhf022vuoq249mtGytG2",
        "created_at": 1709090576567
    }
}

Update Webhook

Update an existing webhook's configuration.

Request Body:

All fields are optional. Only include fields you want to update.

{
    "url": "https://new-domain.com/webhooks/gigstack",
    "events": ["payment.created", "payment.succeeded", "invoice.created"],
    "description": "Updated webhook description",
    "status": "inactive"
}

Example Request:

Delete Webhook

Permanently delete a webhook endpoint.

Example Request:

Example Response:

{
    "success": true,
    "message": "Webhook deleted successfully"
}

🎯 Available Events

Payment Events

payment.created - New payment request created

payment.updated - Payment information updated

payment.succeeded - Payment successfully processed

payment.canceled - Payment canceled

payment.deleted - Payment deleted

payment.upcoming_due_date - Payment due date approaching

Invoice Events

invoice.created - New invoice created

invoice.canceled - Invoice canceled with SAT

invoice.failed - Invoice stamping failed

Receipt Events

receipt.created - New receipt generated

receipt.updated - Receipt information updated

receipt.completed - Receipt stamped successfully

receipt.deleted - Receipt deleted

Customer Events

customer.created - New customer/client created

customer.updated - Customer information updated

customer.deleted - Customer deleted

Service Events

service.created - New service added to catalog

service.updated - Service information updated

service.deleted - Service removed from catalog

🏗️ Webhook Structure

Webhook Object

Field	Type	Description
`id`	string	Unique webhook identifier (prefix: `wh_`)
`url`	string	HTTPS endpoint URL
`events`	array	List of subscribed event types
`status`	string	`active` or `inactive`
`description`	string	Optional description
`owner`	string	User ID who created the webhook
`created_at`	integer	Unix timestamp (milliseconds) of creation

📨 Webhook Payload

When an event occurs, gigstack sends an HTTP POST request to your webhook URL with this structure:

{
    "id": "evt_1234567890",
    "type": "payment.succeeded",
    "created": 1709090576567,
    "livemode": true,
    "data": {
        "object": {
            "id": "payment_1234567890",
            "amount": 1000.00,
            "status": "succeeded",
            ...
        }
    }
}

Payload Fields

id (string) - Unique event identifier

type (string) - Event type (matches subscribed events)

created (integer) - Unix timestamp of event occurrence

livemode (boolean) - true for production, false for test mode

data.object (object) - The full resource object that triggered the event

🔐 Security Best Practices

1. Use HTTPS Endpoints

Always use HTTPS URLs for production webhooks to ensure secure data transmission.

{
    "url": "https://your-domain.com/webhooks/gigstack"
}

2. Validate Webhook Source

Implement verification to ensure webhooks are from gigstack:

Verify the request originates from gigstack's IP ranges

Use request signatures (if implemented)

Validate the payload structure

3. Idempotency

Handle duplicate events gracefully by tracking event IDs:

4. Respond Quickly

Return a 2xx status code within 5 seconds to acknowledge receipt:

💡 Implementation Examples

Node.js / Express

Python / Flask

PHP

🎯 Common Use Cases

1. Payment Confirmation Email

2. Invoice Notification

3. Receipt Backup

🔍 Testing Webhooks

Using webhook.site

For development and testing, use webhook.site to inspect webhook payloads:

Local Testing with ngrok

Start your local server:

Create an ngrok tunnel:

Use the ngrok HTTPS URL in your webhook:

💡 Best Practices

Subscribe to specific events - Only listen to events you need to reduce noise

Use inactive status for testing - Create webhooks with status: "inactive" to test configuration before enabling

Implement retry logic - Handle temporary failures gracefully

Log webhook events - Keep audit logs of received webhooks for debugging

Monitor webhook performance - Track delivery success rates and response times

Version your webhook endpoints - Use versioned URLs (e.g., /webhooks/v1/gigstack) for easier updates

Handle all event types - Include a default case for unknown event types to future-proof your integration

Payments API - Process payments that trigger webhook events

Invoices API - Create invoices that generate webhook events

Receipts API - Manage receipts with webhook notifications

Clients API - Customer management with webhook events

🚨 Error Handling

Invalid Webhook URL

{
    "message": "Invalid webhook data",
    "error": "URL must be a valid HTTPS endpoint"
}

Invalid Event Type

{
    "message": "Invalid webhook data",
    "error": "Invalid event type: 'invalid.event'"
}

Webhook Not Found

{
    "message": "Webhook not found",
    "error": "The specified webhook does not exist"
}

Missing Required Fields

{
    "message": "Invalid webhook data",
    "error": "Missing required field: events"
}

Need help with webhook integration? Check our support documentation or contact support@gigstack.io

Webhooks

Webhooks API Guide#

📋 Overview#

🔑 Key Features#

📚 Endpoints#

List Webhooks#

Get Webhook#

Create Webhook#

Update Webhook#

Delete Webhook#

🎯 Available Events#

Payment Events#

Invoice Events#

Receipt Events#

Customer Events#

Service Events#

🏗️ Webhook Structure#

Webhook Object#

📨 Webhook Payload#

Payload Fields#

🔐 Security Best Practices#

1. Use HTTPS Endpoints#

2. Validate Webhook Source#

3. Idempotency#

4. Respond Quickly#

💡 Implementation Examples#

Node.js / Express#

Python / Flask#

PHP#

🎯 Common Use Cases#

1. Payment Confirmation Email#

2. Invoice Notification#

3. Receipt Backup#

🔍 Testing Webhooks#

Using webhook.site#

Local Testing with ngrok#

💡 Best Practices#

🔗 Related Resources#

🚨 Error Handling#

Invalid Webhook URL#

Invalid Event Type#

Webhook Not Found#

Missing Required Fields#

Webhooks API Guide

📋 Overview

🔑 Key Features

📚 Endpoints

List Webhooks

Get Webhook

Create Webhook

Update Webhook

Delete Webhook

🎯 Available Events

Payment Events

Invoice Events

Receipt Events

Customer Events

Service Events

🏗️ Webhook Structure

Webhook Object

📨 Webhook Payload

Payload Fields

🔐 Security Best Practices

1. Use HTTPS Endpoints

2. Validate Webhook Source

3. Idempotency

4. Respond Quickly

💡 Implementation Examples

Node.js / Express

Python / Flask

PHP

🎯 Common Use Cases

1. Payment Confirmation Email

2. Invoice Notification

3. Receipt Backup

🔍 Testing Webhooks

Using webhook.site

Local Testing with ngrok

💡 Best Practices

🔗 Related Resources

🚨 Error Handling

Invalid Webhook URL

Invalid Event Type

Webhook Not Found

Missing Required Fields