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"
}

For additional assistance, 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