Pike13 For Developers
Get Started
Authentication
Core API
Reporting API
Webhooks API
Announcements

Webhooks API Documentation BETA

Get Started

Follow these simple steps to register your app and get started with the Pike13 Webhooks API. Only OAuth2 tokens registered to those with the role of owner or higher can access the Webhooks API.

API Description

The purpose of the Webhooks API is to automatically notify you and your services of changes within your business. Remember, only staff members with the role of owner or higher have access to the API. For example, when a new client signs up for your business, we'll automatically send you a JSON payload.

Interaction with the Webhooks API is two parts: subscribing to topics and receiving notifications.

Subscribing

Subscribe using the REST API endpoint. Note that it conforms to JSON API version 1.0. Choose what kinds of notifications should be sent based on available topics.

Receiving

Receive notifications through POST requests. The payload is automatically POSTed to the target server when a change corresponding to a webhook happens.

Example Flow

Once you have an OAuth2 token for an owner of your business, you can subscribe to an available topic.

Let's create a webhook that triggers whenever a new person is created in your business:

SUBSCRIPTION REQUEST
curl -X POST https://mybiz.pike13.com/api/v3/webhooks \
-H 'Authorization: Bearer XXXXXX' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
  "data": {
    "type": "webhooks",
      "attributes": {
        "target": "https://target.example.com",
        "topic": "person.created"
        }
      }
    }'

The target attribute specifies the endpoint to which we will send a notification.

SUBSCRIPTION RESPONSE
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1",
    "type": "webhooks",
    "links": {
      "self": "https://subdomain.pike13.com/api/v3/webhooks/1"
    },
    "attributes": {
      "account_id": 1,
      "business_id": 1,
      "topic": "person.created",
      "target": "https://target.example.com/",
      "name": null,
      "description": null
    }
  }
}

After this successful subscription, if a person is created for the business, a server on https://target.example.com/ will receive a message like this:

NOTIFICATION PAYLOAD
POST https://target.example.com/
Content-Type: application/json

{
  "topic": "person.created",
  "webhook_id": 1,
  "business_id": 1,
  "data": {
    "people": [
      {
        "id": 10,
        "address": null,
        "birthdate": null,
        "business_id": 1,
        "deleted_at": null,
        "dependents": [

        ],
        "email": null,
        "first_name": "John",
        "guardian_email": null,
        "guardian_name": "Nathan Doe",
        "hidden_at": null,
        "is_member": false,
        "joined_at": "2019-02-19T23:24:02Z",
        "last_name": "Doe",
        "location": {
          "id": 30742,
          "name": "Example Business",
          "slug": "example-business"
        },
        "middle_name": null,
        "name": "John Doe",
        "phone": "123 456 7890",
        "primary_staff_member": {
          "id": 2,
          "name": "Joseph Cremin"
        },
        "providers": [

        ],
        "secondary_info_field": "No Membership",
        "timezone": "America/Los_Angeles",
        "updated_at": "2019-02-19T23:24:02Z"
      }
    ]
  }
}

Once you have received this payload, you must respond with a 200 status code within 10 seconds, or else it is considered an error on our end.

The data field shows the most up to date status of the resource, in this case a person. It is not identical to the json returned by the person desk endpoint If you require more fields about a person, access the corresponding Core API endpoint upon receiving a webhook:
/api/v2/desk/people/:id

Invoice

Core API resource payload url:

Desk

GET /api/v2/desk/invoices/:id

See the core api doc

Resource Attributes

data.invoices[0]
idintegerThe ID of the invoice.
invoice_numberstringA unique bill identifier for this business, a.k.a. bill number.
invoice_datestringThis invoice's due date.
total_centsintegerThe amount total in cents for this invoice.
totalstringThe amount total in localized currency for this invoice.
outstanding_amount_centsintegerThe amount outstanding in cents.
outstanding_amountstringThe amount outstanding in localized currency.
discount_total_centsintegerThe sum of all discounts in cents.
discount_totalstringThe sum of all discounts in localized currency.
adjustment_total_centsintegerThe sum of all adjustments in cents.
adjustment_totalstringThe sum of all adjustments in localized currency.
included_tax_total_centsintegerThe sum of all included taxes in cents.
included_tax_totalstringThe sum of all included taxes in localized currency.
additional_tax_total_centsintegerThe sum of all additional taxes in cents.
additional_tax_totalstringThe sum of all additional taxes in localized currency.
currencystringThe currency ISO code.
statestringThe current state of the invoice. Either 'open', 'closed', 'canceled', 'cart', 'cart_hidden', or 'on_hold.'
state_eventsarrayAn array of strings containing the valid state events when calling to update the invoice.
invoice_itemsobject

Information regarding the item the invoice is about

idintegerThe ID of the item the invoice is for.
namestringThe name of the item the invoice is for.
descriptionstringThe full description of the item the invoice is for.
recipientsarray

Array of people who received this item.

idintegerThe ID of the person who the invoice is for.
namestringThe full name of the person who the invoice is for.
emailstringThe email address of the person who the invoice is for.
adjustmentsarray

Array of adjustments to the invoice item, documenting changes in the item within this invoice.

idintegerThe ID of the adjustment.
typestringPossible values include: 'Adjustment' for the price, 'CreditAdjustment' for credit, 'Discount' for discounts, 'PriceOverride' for overrides on the price, 'ProrateAdjustment' for proration, and 'TaxAdjustment' for taxes.
namestringThe name for the adjustment.
created_atstringThe date the adjustment was created.
amount_centsintegerEither the amount of the fixed price discount or the computed amount of the percent discount in cents.
amountintegerEither the amount of the fixed price discount or the computed amount of the percent discount in localized currency.
percentintegerOptional. The percentage, if it is a percent adjustment. This can be negative for TaxAdjustments.
sourceobject

Optional. The source of the invoice item adjustment

idintegerThe ID of the source.
typestringThe type of the source.
detailobject

Details regarding the item the invoice is for

idintegerThe ID the of details for the item.
typestringThe object type of the item, i.e 'Membership', 'SignupFee'.
start_datestringOptional. The start date of the item.
count_descriptionstringOptional. How often the item is used.
extended_descriptionarrayOptional. The extended description of the item.
initial_punchcard_count_descriptionstringOptional. How many punches the card starts with.
has_termsbooleanOptional. True if the item has terms.
plan_product_idintegerOptional. The ID for the product plan.
product_idintegerOptional. The ID for the product.
retail_product_idintegerOptional. The ID for the retail product.
serviceobject

Optional. The service the item falls under

idintegerThe ID of the service
paymentsarray

The payments that have already been made on the invoice

idintegerThe ID of the payment.
descriptionstringThe description of the payment.
statestringThe state of the payment.
amount_centsintegerThe amount in cents of the payment.
amountstringThe amount in localized currency of the payment.
maximum_refund_centsintegerThe maximum amount refundable in cents of the payment.
maximum_refundstringThe maximum amount refundable in localized currency of the payment.
created_atstringThe date the payment was created.
voided_atstringThe date the payment was voided.
error_messagestringOptional. The error message for the payment if it failed.
refundsobject

Optional. The refunds for the payments

idintegerThe ID of the refund.
amount_centsintegerThe amount in cents of the refund.
amountstringThe amount in localized currency of the refund.
statestringThe state of the refund.
payment_idintThe ID of the payment the refund is for.
descriptionstringThe description of the refund.
created_atstringThe date the refund was created.
voided_atstringThe date the refund was voided.
payerobject

Optional. The person who paid the payment

idintegerThe ID of the person who the invoice is for.
namestringThe full name of the person who the invoice is for.
emailstringThe email address of the person who the invoice is for.
personobject

Optional. Information regarding the person who the invoice is for

idintegerThe ID of the person attached to this invoice.
namestringThe name of the person attached to this invoice.
emailstringThe email of the person attached to this invoice.
couponobject

Optional. Information regarding a coupon for the invoice, if there is any

idintegerThe ID of the promotion.
codestringThe code for the promotion.
namestringThe name of the promotion.
descriptionstringThe description of the promotion.
discount_percentintegerOptional. The discount percent of the promotion.
discount_amount_centsintegerOptional. The fixed amount discount in cents of the promotion.
discount_amountintegerOptional. The fixed amount discount in localized currency of the promotion.
previousobject

Optional. If this an UPDATE payload - additional information about the changed attributes

variesobjectVarious details about the changed attributes of the invoice.

A Special Note about Invoice Topics

The webhook topic 'invoice.new' is suggested for most uses instead of 'invoice.created'.

The 'invoice.new' topic shields users from being exposed to some of the internal state changes that invoices go through during their lifecycle. For instance, a new invoice object is created every time a shopping cart is created - but most people aren't really interested in an invoice until it is in a billable or paid state.

invoice.new

The 'invoice.new' webhook topic is recommended as the best way to get invoices when they are created from an end user's perspective. It will trigger whenever an invoice is created or updated so long as the state the invoice is entering is NOT CART. The possible states for an invoice are: OPEN, CLOSED, CANCELLED, CART, CART_HIDDEN, ON_HOLD.

Payload Example

Invoice New Webhook Payload

invoice.created

The 'invoice.created' webhook topic is not recommended for most users. It triggers every time an internal invoice record is created. For example, if someone starts shopping you would get a notification even if the shopping cart is later abandoned and what we call an "invoice" is never actually created in a billable state. Instead we recommend you use the 'invoice.new' trigger.

Payload Example

Invoice Created Webhook Payload

invoice.updated

Changes to these fields trigger an "invoice.updated" notification. Payment changes are handled by the Transactions webhook topic.
statestringPossible values: open, closed, cancelled, cart, cart_hidden, on_hold
personpersonThe assigned person { id, name, email }
receipt_emailstringemail@example.com
locationobject{ id, name, slug }
commission_recipientperson{ id, name, email }
tip_recipientperson{ id, name, email }

Previous values supported by the "invoice.updated" topic
statestringPossible values: open, closed, cancelled, cart, cart_hidden, on_hold
personpersonThe assigned person { id, name, email }
receipt_emailstringemail@example.com
locationobject{ id, name, slug }
commission_recipientperson{ id, name, email }
tip_recipientperson{ id, name, email }

Payload Example

Invoice Updated Webhook Payload

Person

Core API resource payload url:

Desk

GET /api/v2/desk/people/:id

See the core api doc

Resource Attributes

data.people[0]
idintegerPerson's ID.
first_namestringPerson's first name.
middle_namestringPerson's middle name.
last_namestringPerson's last name.
namestringPerson's full name.
emailstringPerson's email address. Email address formatting is enforced.
is_memberbooleanWhether person is a member of the business.
addressstringPerson's physical address.
phonestringPerson's phone number.
birthdatedatePerson's date of birth.
guardian_namestringFull name of person's guardian.
guardian_emailstringEmail address of person's guardian.
timezoneintegerTimezone of a person.
business_idintegerID of the business to which a person belongs.
updated_attimestampTimestamp for when the person was last updated in the business.
deleted_attimestampTimestamp for when the person was deleted from the business. Null if not deleted.
hidden_attimestampTimestamp for when the person was hidden in the business. Null if not hidden.
joined_attimestampTimestamp for when the person joined the business.
secondary_info_fieldstringClient info that appears below this person's name when listing clients.
primary_staff_memberobject

Optional. Staff information for this person.

idintegerStaff member's person ID.
namestringName of staff member.
locationobject

Optional. Location information for this person.

idintegerThe ID for this location.
nameintegerThe name of this location.
slugintegerThe slug (unique string) for this location.
dependentsarray

Not supported on person.created.

Array of people objects who are managed by the person. Empty if no such people are managed.

idintegerPerson's ID.
first_namestringPerson's first name.
middle_namestringPerson's middle name.
last_namestringPerson's last name.
namestringPerson's full name.
is_memberbooleanWhether person is a member of the business.
emailstringPerson's email address. Email address formatting is enforced.
addressstringPerson's physical address.
phonestringPerson's phone number.
birthdatedatePerson's date of birth.
guardian_namestringFull name of person's guardian.
guardian_emailstringEmail address of person's guardian.
business_idintegerID of the business to which a person belongs.
timezoneintegerTimezone of a person.
updated_attimestampTimestamp for the most recent update of a person.
deleted_attimestampTimestamp for when the person was deleted from the business. Null if not deleted.
hidden_attimestampTimestamp for when the person was hidden in the business. Null if not hidden.
joined_attimestampTimestamp for when the person joined the business.
secondary_info_fieldstringClient info that appears below this person's name when listing clients.
custom_fieldsarray

Array of person_custom_field objects with the following schema:

custom_field_idintegerID of the custom field.
idintegerID of person's custom field response.
namestringName of the custom field.
valuestringValue of the person's custom field response.
providersarray

Not supported on person.created.

Array of people objects who are account managers of the person. Empty if no account managers exist. Same JSON structure as dependents.

profile_photoobject

Not supported on person.created.

Optional. Shows url of profile photo if one is available.

x50stringUrl of profile photo, sized 50x50.
x100stringUrl of profile photo, sized 100x100.
x200stringUrl of profile photo, sized 200x200.
x400stringUrl of profile photo, sized 400x400.

person.created

Triggers when a new person is added to a business.

Payload Example

Person Created Webhook Payload

person.updated

Triggers when a specific fields of a person are updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
first_namestringPerson's first name.
middle_namestringPerson's middle name.
last_namestringPerson's last name.
emailstringPerson's email address. Email address formatting is enforced.
addressstringPerson's physical address.
phonestringPerson's phone number.
birthdatedatePerson's date of birth.
guardian_namestringFull name of person's guardian.
guardian_emailstringEmail address of person's guardian.
joined_attimestampTimestamp for when the person joined the business.
is_memberbooleanWhether person is a member of the business.
custom_fieldsobject

A notification will be sent whenever an individual person_custom_field object's value changes or is created for the person:

idintegerID of person's custom field response.
valuestringValue of the person's custom field response.

This topic supports previous values within data:

data
peoplearrayArray of one person updated in the business.
previousobject

Previous values of the resource. The following are supported:

first_namestringPerson's first name.
middle_namestringPerson's middle name.
last_namestringPerson's last name.
emailstringPerson's email address. Email address formatting is enforced.
addressstringPerson's physical address.
phonestringPerson's phone number.
birthdatedatePerson's date of birth.
guardian_namestringFull name of person's guardian.
guardian_emailstringEmail address of person's guardian.
is_memberbooleanWhether person is a member of the business.
updated_attimestampTimestamp for when the person was last updated in the business.
hidden_attimestampTimestamp for when the person was hidden in the business. Null if not hidden.
joined_attimestampTimestamp for when the person joined the business.
primary_staff_member_idintegerPerson's staff member id
custom_fieldsobject
idintegerID of person's custom field response.
valuestringValue of the person's custom field response.

Payload Example

Person Updated Webhook Payload

Person Plan

Resource Attributes

data.person_plans[0]
idintegerID of the person_plan association.
created_attimestampTimestamp for when this person became associated with this plan.
deactivated_attimestampTimestamp for when this person was removed from this plan, if applicable.
exhausted_attimestampTimestamp for when this person_plan was exhausted, if applicable.
updated_attimestampTimestamp for when this person_plan was updated, if applicable.
personobject

Details of the person for this person_plan.

idintegerID for this person.
namestringName of this person.
emailstringEmail for this person.
planobject

Details of the plan for this person_plan.

idintegerID for this plan.
descriptionstringDescription of this plan.
typestringType of this plan. One of ['Pack', 'Prepaid', 'Membership'].
plan_product_idintegerID of product associated with this plan.
countintegerMaximium count (limit) for the number of punches for this plan during the 'limit_period'.
staff_member_idintegerStaff Member ID for this plan.
location_idintegerLocation ID for this plan.
pricestringPrice formatted in currency units for this plan.
price_centsintegerPrice in cents for this plan.
limit_periodstringLimit period for this plan if any. One of ['weekly', 'monthly'].
start_datedateStart date for this plan.
end_datedateEnd date for this plan.
cancelled_attimestampTimestamp for when this plan was cancelled, if applicable.
updated_attimestampTimestamp for when this plan was updated.
created_attimestampTimestamp for when this plan was created.

person_plan.created

Triggers whenever a new person_plan is created.

Payload Example

PersonPlan Created Webhook Payload

person_plan.updated

Triggers whenever a person_plan is updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
person_idintegerThe person on the plan
deactivated_attimestampThe date this plan was deactivated
exhausted_atstringThe date the person plan was exhausted

This topic supports previous values within data:

data
person_plansarrayArray of one person plan updated in the business.
previousobject

Previous values of the resource. The following are supported:

person_idintegerID of the person for this person_plan
deactivated_attimestampThe date this plan was deactivated
exhausted_atstringThe date the person plan was exhausted
updated_atstringThe date the person plan was last updated

Payload Example

PersonPlan Updated Webhook Payload

Plan

Resource Attributes

data.plans[0]
idintegerID for this plan.
descriptionstringDescription of this plan.
typestringType of this plan. One of ['Pack', 'Prepaid', 'Membership'].
plan_product_idintegerID of product associated with this plan.
countintegerMaximium count (limit) for the number of punches for this plan during the 'limit_period'.
staff_member_idintegerStaff Member ID for this plan.
location_idintegerLocation ID for this plan.
pricestringPrice formatted in currency units for this plan.
price_centsintegerPrice in cents for this plan.
limit_periodstringLimit period for this plan if any. One of ['weekly', 'monthly'].
start_datedateStart date for this plan.
end_datedateEnd date for this plan.
cancelled_attimestampTimestamp for when this plan was cancelled, if applicable.
updated_attimestampTimestamp for when this plan was updated.
created_attimestampTimestamp for when this plan was created.
peoplearray

Array of people objects who are on this plan. Empty if there are none.

idintegerID for this person.
namestringName of this person.
emailstringEmail for this person.

plan.updated

Triggers when specific fields of a plan are updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
description
price_cents
count
staff_member_id
limit_period
start_date
end_date
cancelled_at

This topic supports previous values within data:

data
plansarrayArray of one plan updated in the business.
previousobject

Previous values of the resource. The following are supported:

descriptionstringDescription of this plan.
pricestringPrice formatted in currency units for this plan.
price_centsintegerPrice in cents for this plan.
countintegerMaximium count (limit) for the number of punches for this plan during the 'limit_period'.
staff_member_idintegerStaff Member ID for this plan.
limit_periodstringLimit period for this plan if any. One of ['weekly', 'monthly'].
start_datedateStart date for this plan.
end_datedateEnd date for this plan.
cancelled_attimestampTimestamp for when this plan was cancelled, if applicable.
updated_attimestampTimestamp for when this plan was updated.

Payload Example

Plan Updated Webhook Payload

Punchcard

Punchcards track the amount of event occurrences the people associated with the punchcard can attend. A new punchcard starts every week if the plan is a weekly plan, every month if the plan is a monthly plan, etc.

Resource Attributes

data.punchcards[0]
idintegerThe punchcard's ID.
countintegerThe number of punches provided by the punchcard.
remainingintegerThe number of punches remaining on the punchcard.
start_datedateThe first day the punchcard is active.
end_datedateThe last day the punchcard is active.
peopleobject

idintegerPerson's ID.
namestringPerson's full name.
emailstringPerson's email address. Email address formatting is enforced.
planobject

Details of the associated plan.

idintegerID for this plan.
descriptionstringDescription of this plan.
typestringType of this plan. One of ['Pack', 'Prepaid', 'Membership'].
countintegerThe number of punches each punchcard starts with for the duration of the limit period.
limit_periodstringLimit period for this plan if any (e.g. 'weekly', 'monthly'). The 'count' variable relates to this time period.
updated_attimestampTimestamp for when the punchcard was last updated.

punchcard.started

Triggers when a punchcard becomes active for the current limit period.

Payload Example

Punchcard Started Webhook Payload

punchcard.updated

Triggers when a certain properties of a punchcard are updated.

The specific list of fields that trigger an update are:

Changes to these fields trigger a notification
count
remaining
start_date
end_date
data
peoplearrayArray of one updated punchcard.
previousobject

Previous values of the resource. The following are supported:

countintegerThe number of punches provided by the punchcard.
remainingintegerThe number of punches remaining on the punchcard.
start_datedateThe first day the punchcard is active.
end_datedateThe last day the punchcard is active.
updated_attimestampTimestamp for when the punchcard was last updated.

punchcard.updated

Triggers when a punchcard is updated.

Payload Example

Punchcard Updated Webhook Payload

punchcard.deleted

Triggers when a punchcard is deleted.

Payload Example

Punchcard Deleted Webhook Payload

Transaction

By subscribing to a transaction topic, you will be notified of two transaction types: payments and refunds. Check the data.transactions[0].type to differentiate.

Resource Attributes

data.transactions[0]
idintegerThe transaction's ID.
invoice_idintegerID of the associated invoice.
currency_codestringThe currency ISO code.
amount_centsintegerThe amount in cents of the transaction.
amountstringThe amount in localized currency of the transaction.
error_messagestringThe error message for the transaction if it failed.
descriptionstringThe description of the transaction.
voided_attimestampThe date the transaction was voided.
payment_type_idintegerThe type id of the available payment method.
typestringType is one of ['Payment', 'Refund'].
settledbooleanWhether transaction has settled according to the payment gateway. Settled transactions cannot be voided.
statestringOne of ['failed', 'processing', 'completed', 'checkout']
uuiduuidUUID of the transaction.
autobillbooleanWhether or not this transaction is on autobill.
payment_idintegerID of the payment. Only included if the transaction is a Refund.
external_transaction_idintegerID of the transaction according to the external transaction processor.
payment_typestringType of payment. One of ['cash', 'check', 'creditcard', 'ach', 'comp', 'free', 'external_creditcard', 'square', 'paypal', 'external', 'credit'].
created_attimestampTimestamp for when transaction was created.
updated_attimestampTimestamp for when transaction was last updated.
invoiceobject

Details of the associated invoice.

idintegerID of the invoice.
total_centsstringThe amount total in cents for this invoice.
totalstringThe amount total in localized currency for this invoice.
state_eventsstringAn array of strings containing the valid state events when calling to update the invoice.
send_receiptstringWas a receipt email sent?
receipt_emailstringThe email address the invoice was sent to, if any.
currencystringThe type of currency the invoice is charged in, i.e 'USD'.
statestringThe current state of the invoice. Either 'open', 'closed', 'canceled', 'cart', 'cart_hidden', or 'on_hold.'

transaction.created

Triggers when a new transaction is created.

Payload Example

Transaction Created Webhook Payload

transaction.updated

Triggers when a certain properties of a transaction are updated.

The specific list of fields that trigger an update are:

Changes to these fields trigger a notification
invoice_id
currency_code
amount_cents
error_message
description
voided_at
payment_type_id
type
settled
state
uuid
autobill
payment_id
external_transaction_id
payment_type
data
peoplearrayArray of one updated transaction.
previousobject

Previous values of the resource. The following are supported:

invoice_idintegerID of the associated invoice.
currency_codestringThe currency ISO code.
amount_centsintegerThe amount in cents of the transaction.
error_messagestringThe error message for the transaction if it failed.
descriptionstringThe description of the transaction.
voided_attimestampThe date the transaction was voided.
payment_type_idintegerThe type id of the available payment method.
typestringType is one of ['Payment', 'Refund'].
settledbooleanWhether transaction has settled according to the payment gateway. Settled transactions cannot be voided.
statestringOne of ['failed', 'processing', 'completed', 'checkout']
uuiduuidUUID of the transaction.
autobillbooleanWhether or not this transaction is on autobill.
payment_idintegerID of the payment. Only included if the transaction is a Refund.
external_transaction_idintegerID of the transaction according to the external transaction processor.
payment_typestringType of payment. One of ['cash', 'check', 'creditcard', 'ach', 'comp', 'free', 'external_creditcard', 'square', 'paypal', 'external', 'credit'].
updated_attimestampTimestamp for when transaction was last updated.

Payload Example

Transaction Updated Webhook Payload

Visit

Core API resource payload url:

Desk

GET /api/v2/desk/visits/:id

See the core api doc

Resource Attributes

data.visits[0]
idintegerThe visit's ID.
person_idintegerID of the associated person.
event_occurrence_idintegerID of the associated event occurrence.
statestringStatus of the visit. One of ['registered', 'reserved', 'noshowed', 'late_canceled', or 'completed']
registered_attimestampTimestamp for when visit was registered. Typically, this is when the visit was created.
completed_attimestampTimestamp for when visit was marked as complete by a staff member.
noshow_attimestampTimestamp for when visit was marked as no-show by a staff member.
cancelled_attimestampTimestamp for when visit was marked as a late cancel by a staff member.
created_attimestampTimestamp for when visit was created.
updated_attimestampTimestamp for when visit was last updated.
paidbooleanTrue if this visit has been paid for.
paid_for_bystringDescription of the plan used to pay for the visit.
punch_idintegerThe id of the punch if present.
only_staff_can_cancelbooleanTrue if only staff can cancel this visit.
event_occurrenceobject

Details of the associated event_occurrence.

idintegerID of the event occurrence.
namestringName of the event occurrence.
statestringOne of ['reserved', 'active', 'cancelled', 'deleted'].
start_attimestampTimestamp for when event occurrence begins.
end_attimestampTimestamp for when event occurrence ends.
service_idintegerID of the associated service.
event_idintegerID of the associated event.
location_idintegerID of the associated location.
staff_membersarray

Details of the associated list of staff members.

idintegerID of the staff member.
namestringName of the staff member.
has_profilebooleanTrue if staff member has a profile.
personobject

Details of the associated person.

idintegerID of the person.
namestringName of the person.
emailstringEmail of the person.

A Special Note about Visit Topics

The webhook topic 'visit.new' is suggested for most uses instead of 'visit.created'.

The 'visit.new' topic shields users from being exposed to some of the internal state changes that visits go through during their lifecycle. For instance, a new visit object is created in a "reserved" state before the user has paid for their registration. Most users will be interested in a visit once it's been "booked."

visit.new

Triggers when a new visit is created in a state other than "reserved." Also triggers when a visit transitions from "reserved" to "registered", "completed", "noshowed", or "late_cancel."

Payload Example

Visit New Webhook Payload

visit.created

Triggers whenever a new visit is created, including those in a pre-booked "reserved" state.

Payload Example

Visit Created Webhook Payload

visit.deleted

Triggers when a visit is deleted.

Payload Example

Visit Deleted Webhook Payload

visit.updated

Triggers when specific fields of a visit are updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
statestringStatus of the visit. One of ['registered', 'reserved', 'noshowed', 'late_canceled', or 'completed']
completed_attimestampTimestamp for when visit was marked as complete by a staff member.
noshow_attimestampTimestamp for when visit was marked as no-show by a staff member.
cancelled_attimestampTimestamp for when visit was marked as a late cancel by a staff member.
punch_idintegerThe id of the punch if present.

This topic supports previous values within data:

data
visitsarrayArray of one visit updated in the business.
previousobject

Previous values of the resource. The following are supported:

statestringStatus of the visit. One of ['registered', 'reserved', 'noshowed', 'late_canceled', or 'completed']
completed_attimestampTimestamp for when visit was marked as complete by a staff member.
noshow_attimestampTimestamp for when visit was marked as no-show by a staff member.
cancelled_attimestampTimestamp for when visit was marked as a late cancel by a staff member.
punch_idintegerThe id of the punch if present.
updated_attimestampTimestamp for when visit was last updated.

Payload Example

Visit Updated Webhook Payload

Webhook

Represents a subscription to a topic for changes within a business. Franchises will be automatically notified of changes in all franchisees provided the franchise has created a webhook with a relevant topic. Every webhook endpoint is scoped by the access token and the business.

The subscription endpoint conforms to JSON API version 1.0.

GET /api/v3/webhooks

Returns all webhooks created by an account and scoped by the subdomain.

Show curl example

GET /api/v3/webhooks/:id

Returns a specific webhook.

POST /api/v3/webhooks

Create a webhook. account_id and business_id are not directly settable.

Required Attributes
topicstringMust be a valid topic.
targethttps urlAn endpoint for Pike13 servers to POST a payload to.
Optional Attributes
namestringA name for the webhook.
descriptionstringDescription.

Show curl example

PATCH /api/v3/webhooks/:id

Update a specific webhook. account_id and business_id are immutable.

Show curl example

DELETE /api/v3/webhooks/:id

Deletes a specific webhook.

Show curl example

POST bodies

Notifications are sent within HTTP POST bodies. The common format for notifications hitting target servers is

NOTIFICATION PAYLOAD
POST https://target.example.com/
Content-Type: application/json

{
  "topic": "person.created",
  "data": { <topic fields> },
  "target_url": "https://target.example.com",
  "webhook_id": 1
}
Where the supported fields are documented for each topic. If the webhook is a <resource>.updated topic:
TOPIC FIELDS (changed exists only on *.updated topics)
{
  ...Supported fields for the topic,
  "changed": {<previous states of the corresponding field>}
}
A full example of a person.updated payload illustrates that the previous name for a person was "John" but was updated to "Jon":
EXAMPLE: updated_person_payload.data.changed
# TODO

The indicated topic fields within data is similar to the json that Core API would return for the endpoint corresponding to the person.created topic. If you need other fields on the resource, you would make your own api call to the resource's corresponding Core API endpoint.

Requirements

  • The target url specified when creating a webhook must be be https.
  • Servers must respond with a 200 (Success) status code upon receiving a notification within 10 seconds.
  • Opening a connection to servers will timeout if it takes longer than 10 seconds.
  • If a target url server responds with a 410 (Gone) status code the webhook will be deleted.

Notification Lifetime

Generally, a notification will reach target servers within minutes and likely sooner. In the event that notification destinations are unavailable when POSTing, the notification will be retried based on the response status code returned. However, notifications may expire if the target server does not respond with a 200 after 20 retries.

Retry Status Codes
429
500-599

All other status codes returned by servers will result in the dropping the notification immediately. To help with debugging, use the trigger sample notification endpoint to receive a notification and the notifications endpoint to see the most recent POSTs that have been attempted.

Retry Intervals

Retries are done with jittered exponential backoff. We will retry sending a notification 20 times over the next 4 days.

Debugging Notifications

View recent notifications.

GET /api/v3/webhooks/:webhook_id/notifications

Returns recent notifications belonging to a webhook. Notifications are kept for 7 days after creation, represented as ttl, a date time in seconds.

Show curl example

Trigger sample notification.

POST /api/v3/webhooks/:webhook_id/trigger_sample_notification

Sends a sample notification to a webhook's target URL. Does not make a real data change.

Show curl example