Webhooks API Documentation

• Overview
• Fields
  • Event Type Options
  • Event Object
    • Check-In Object
    • Payment Complete Object
  • Entry Method Values
  • Invoice Status Values
  • Payment Type Values
  • Payment Method Type Values
  • Line Item Purchase Type Values
• Operations
  • List
  • Read
  • Create
  • Update
  • Delete
  • Example Webhook Object

Overview

This collection contains configured webhooks. Each webhook instructs Capitan to make a POST request to a configured URL whenever a particular type of event occurs.

Fields

Name	Type	Restrictions	Required?	Description
id	integer	Automatic	Automatic	The unique identifier of the webhook.
event_type	string	Must be one of the supported event type options.	Yes	Which type of event will be sent via the webhook.
webhook_url	string	Must be a valid URL, including the protocol (http, https).	Yes	The URL which will receive the webhook.
secret	string	Must be no more than 255 characters in length.	No	A secret which will be included in all events published via this webhook. Can be used to verify that the events are authentic.
created_at	string (ISO-8601 datetime)	Automatic	Automatic	When the webhook was created.
updated_at	string (ISO-8601 datetime)	Automatic	Automatic	When the webhook was last updated.

Event Type Options

Name	Syntax	Description
Check In	check_in	This event occurs when a customer checks into a location within the organization.
Payment Complete	payment_complete	This event occurs whenever a payment is completed, including payments synced from a POS integration. A single invoice that is paid in multiple installments (such as a deposit followed by the remaining balance) produces one event per completed payment.

Event Object

Each event POSTed via the webhook is a JSON object with the following fields:

Name	Type	Description
webhook_event_id	integer	The unique ID of the webhook event.
event_type	string (one of the event type options)	The type of event.
secret	string	The configured secret for the webhook.
event	JSON object	The event. Its fields depend on the event type; see below for each event type's list of fields.

Check-In Object

Check-in objects contain the following fields:

Name	Type	Description
id	integer	The unique ID of the check-in.
customer_id	integer	The unique ID of the customer who checked in.
customer_first_name	string	The first name of the customer who checked in.
customer_last_name	string	The last name of the customer who checked in.
customer_birthday	string (ISO-8601 date)	The birthday of the customer who checked in.
customer_email	string or null	The email of the customer who checked in (or null if they do not have one).
check_in_datetime	string (ISO-8601 datetime)	When the check-in occurred.
entry_method	string (one of the entry method values)	The type of entry method used for the check-in.
entry_method_description	string	A string describing the entry method (such as a membership or entry pass name).
location_id	integer	The unique ID of the location where the check-in occurred.
location_name	string	The name of the location where the check-in occurred.
check_in_count	integer	How many total check-ins the customer had at the time (including this check-in).

Payment Complete Object

Payment complete objects contain the following fields:

Name	Type	Description
id	integer	The unique ID of the payment.
invoice_id	integer	The unique ID of the invoice the payment was made towards.
location_id	integer or null	The unique ID of the location the purchase is attributed to (or null if it could not be attributed to a location).
location_name	string or null	The name of the location the purchase is attributed to (or null if it could not be attributed to a location).
payment_datetime	string (ISO-8601 datetime)	When the payment was made.
currency	string (ISO-4217 code)	The organization's currency as a three-letter code (such as "USD"). Applies to every amount in this event.
payment_amount	string (decimal)	The amount of this payment, inclusive of tax.
payment_processor_fee	string (decimal)	The fee charged by the payment processor for this payment (0 if there was none).
payment_type	string (one of the payment type values)	How the payment was made (such as a card processor, credit, or voucher).
payment_type_description	string	A human-readable description of the payment type.
invoice_status	string (one of the invoice status values)	The status of the invoice after this payment. Use this to distinguish between a deposit (DEP) and a fully paid invoice (COM).
invoice_status_description	string	A human-readable description of the invoice status.
invoice_total_amount	string (decimal)	The total amount owed on the invoice, inclusive of tax.
invoice_total_amount_pre_tax	string (decimal)	The total amount owed on the invoice, excluding tax.
invoice_tax_amount	string (decimal)	The amount of tax on the invoice.
invoice_discount_amount	string (decimal)	The total amount discounted on the invoice (discounts are pre-tax).
invoice_amount_due	string (decimal)	The amount still due on the invoice after this payment, inclusive of tax. Can be negative if the invoice is overpaid.
external_ids	JSON object	IDs which correlate this invoice to an order in an external or POS system; see the external ID fields below.
payment_method	JSON object	Information about the payment method used; see the payment method fields below.
customer	JSON object or null	Information about the customer who made the payment, or null if the payment was not linked to a customer account; see the customer fields below.
line_items	array of JSON objects	The full list of line items on the invoice, so an integration can tell exactly what was purchased; see the line item fields below.

External ID Fields

Each field is null unless it applies to this invoice.

Name	Type	Description
square_order_id	string or null	The ID of the associated order in Square, if any.
lightspeed_created_sale_id	string or null	The ID of the associated sale in Lightspeed, if any.
external_database_id	string or null	The ID of this invoice in the external database it was migrated from (such as Approach or RGP), if any.

Payment Method Fields

Name	Type	Description
type	string (one of the payment method type values)	The kind of payment method used.
type_description	string	A human-readable description of the payment method type.
is_card_present	boolean	Whether a card reader was used, indicating an in-person (card-present) payment as opposed to an online or keyed-in one.
card_brand	string or null	The brand of the card used (such as "Visa"), if a card was used.
card_last4	string or null	The last four digits of the card used, if a card was used.
card_exp_month	integer or null	The expiration month of the card used, if a card was used.
card_exp_year	integer or null	The expiration year of the card used, if a card was used.
bank_name	string or null	The name of the bank, if a bank account was used.
bank_account_last4	string or null	The last four digits of the bank account, if a bank account was used.

Customer Fields

Name	Type	Description
id	integer	The unique ID of the customer.
first_name	string	The first name of the customer.
last_name	string	The last name of the customer.
barcode	string	The customer's barcode (empty if they do not have one).
birthday	string (ISO-8601 date)	The birthday of the customer.
email	string	The email of the customer (empty if they do not have one).
telephone	string	The telephone number of the customer (empty if they do not have one).

Line Item Fields

Name	Type	Description
id	integer	The unique ID of the line item.
description	string	A short description of the purchased product.
purchase_type	string (one of the line item purchase type values)	The kind of product this line item is for.
purchase_type_description	string	A human-readable description of the line item's purchase type.
amount	string (decimal)	The price of the line item, inclusive of tax.
amount_pre_tax	string (decimal)	The price of the line item, excluding tax.
discount_amount	string (decimal)	The amount this line item was discounted (discounts are pre-tax).

Entry Method Values

Name	Syntax
Membership	MEM
Entry Pass	ENT
Event Reservation	EVE
Guest Pass	GUE
Free Entry	FRE
Migrated	MIG

Invoice Status Values

Name	Syntax
Payment Pending	PEN
Deposit Paid	DEP
Payment Complete	COM
Partially Refunded	PRF
Refunded	REF
Cancelled	CAN

Payment Type Values

Name	Syntax
Stripe	STR
Gravity	GRA
MX Merchant	MXM
Mock	MOK
Vend	VEN
Square	SQU
Credit	CRE
Voucher	VOU
Offline	OFF
POS Gift Card	PGI
Migrated	MIG
N/A	NA

Payment Method Type Values

Name	Syntax
N/A	NA
Card	CRD
Bank Account	BNK

Line Item Purchase Type Values

Name	Syntax
Booking	BOO
Membership Initial	MIN
Membership Fix Failed	MFA
Membership Recurring	MRE
Membership Prepaid Freeze Fee	MFR
Membership Add-on Change Fee	MAC
Entry Pass	EPA
Voucher Pack	VPO
Event Voucher	EVV
Gift	GIF
Generic	GEN
Legacy	LEG

Operations

List

Request
GET /api/webhooks/

Response
200 OK
{
    "count": 17,
    "next": "https://api.hellocapitan.com/api/webhooks/?page=2",
    "previous": null,
    "results": [
        {
            "id": 35,
            "event_type": "check_in",
            "webhook_url": "http://example.com/webhook",
            ...
        },
        ...
    ]
}

Read

Request
GET /api/webhooks/35/

Response
200 OK
{
    "id": 35,
    "event_type": "check_in",
    "webhook_url": "http://example.com/webhook",
    ...
}

Create

Request
POST /api/webhooks/
{
    "event_type": "check_in",
    "webhook_url": "http://example.com/webhook2",
    "secret": "12345"
}

Response
201 Created
{
    "id": 53,
    "event_type": "check_in",
    "webhook_url": "http://example.com/webhook2",
    "secret": "12345",
    ...
}

Update

Request
PATCH /api/webhooks/53/
{
    "webhook_url": "http://example.com/webhook3"
}

Response
200 OK
{
    "id": 53,
    "event_type": "check_in",
    "webhook_url": "http://example.com/webhook3",
    "secret": "12345",
    ...
}

Example Webhook Object

An example of a check_in event:

Request
POST http://example.com/webhook3
{
    "webhook_event_id": 351,
    "event_type": "check_in",
    "secret": "12345",
    "event": {
      "id": 114,
      "customer_id": 37512,
      "customer_first_name": "Thomas",
      "customer_last_name": "Anderson",
      "customer_birthday": "1971-09-13",
      "customer_email": null,
      "check_in_datetime": "2025-06-19T20:09:17.095284-04:00",
      "entry_method": "FRE",
      "entry_method_description": "Free Entry, created by Agent Smith",
      "location_id": 14,
      "location_name": "The Matrix",
      "check_in_count": 2
    }
}

An example of a payment_complete event:

Request
POST http://example.com/webhook3
{
    "webhook_event_id": 352,
    "event_type": "payment_complete",
    "secret": "12345",
    "event": {
      "id": 9182,
      "invoice_id": 4471,
      "location_id": 14,
      "location_name": "The Matrix",
      "payment_datetime": "2025-06-19T20:09:17.095284-04:00",
      "currency": "USD",
      "payment_amount": "50.00",
      "payment_processor_fee": "1.75",
      "payment_type": "STR",
      "payment_type_description": "Stripe",
      "invoice_status": "DEP",
      "invoice_status_description": "Deposit Paid",
      "invoice_total_amount": "120.00",
      "invoice_total_amount_pre_tax": "110.09",
      "invoice_tax_amount": "9.91",
      "invoice_discount_amount": "0.00",
      "invoice_amount_due": "70.00",
      "external_ids": {
        "square_order_id": null,
        "lightspeed_created_sale_id": null,
        "external_database_id": null
      },
      "payment_method": {
        "type": "CRD",
        "type_description": "Card",
        "is_card_present": false,
        "card_brand": "Visa",
        "card_last4": "4242",
        "card_exp_month": 8,
        "card_exp_year": 2027,
        "bank_name": null,
        "bank_account_last4": null
      },
      "customer": {
        "id": 37512,
        "first_name": "Thomas",
        "last_name": "Anderson",
        "barcode": "1000000114",
        "birthday": "1971-09-13",
        "email": "neo@example.com",
        "telephone": "+15555550114"
      },
      "line_items": [
        {
          "id": 60231,
          "description": "Annual Membership",
          "purchase_type": "MIN",
          "purchase_type_description": "Membership Initial",
          "amount": "120.00",
          "amount_pre_tax": "110.09",
          "discount_amount": "0.00"
        }
      ]
    }
}