Webhooks

Use webhooks to receive an event whenever certain actions are carried out in Trybe so that your back-end systems can execute actions accordingly.

To enable webhook events, you need to register one or more webhook endpoints and select which events to receive a webhook for.

Example payload

Each webhook sent from Trybe follows a similar format:

{
  "id": "66c36d4eef7657ae2b096128",
  "event": "customer_labels.removed",
  "timestamp": "2024-08-19T16:05:34+00:00",
  "webhook_config_id": "66ba3d8f13e43589da030ad8",
  "site_id": "00000000-0000-0000-0000-111111111111",
  "data": {
    ...
  }
}

id is a unique ID for the webhook event. If a webhook fails and gets retried, the same ID will be used
event is an identifier for the event, following the format [object_type].[action]
timestamp is the time and date that the webhook event was generated
webhook_config_id is the ID of the webhook configuration that was used for the webhook, which may be useful if you have multiple configurations set up
site_id is the ID of the Trybe site that the object in the event belongs to
data is the payload of the webhook which will vary depending on the object and the action

Payload data structure

The format of the data value within the webhook payload will match the format of API responses for the related object. See below for specific examples.

Webhook events

Basket

In the following events, data is an Order object as would be returned from the orderShow operation.

basket.submitted: when an order is submitted, from any source
basket.settled: when an order is checked out
basket.cancelled: When a whole order is cancelled
basket.no_showed: When an order is marked as 'no show'

Basket item

In the following events, data is an OrderItem object as would be returned from the orderAddItem operation.

basket_item.added: When an item is added to a submitted order
basket_item.updated: When an item in a submitted order is updated

Customer

In the following events, data is a Customer object as would be returned from the getCustomer operation

customer.created: When a customer is created
customer.updated: When a customer is updated
customer.deleted: When a customer is deleted (just returns the ID of the deleted customer)

Customer address

In the following events, data is a CustomerAddress object as would be returned from the getCustomerAddress operation

customer_address.created: When an address is added to a customer
customer_address.updated: When a customer's address is updated
customer_address.deleted: When a customer's address is deleted (just returns the ID of the deleted address)

Customer labels

In the following events, data will include a customer_id and an array of labels, each of which is a label object as would be returned from the getCustomerLabels operation.

customer_labels.added: When label(s) are added to a customer
customer_labels.removed: When label(s) are removed from a customer\

Customer notes

In the following events, data is a CustomerNote object as would be returned from the listNotes operation.

customer_note.created: When a note is added to a customer
customer_note.updated: When a customer note is updated
customer_note.deleted: When a customer note is deleted (just returns the ID of the deleted note)

Marketing preferences

In the following event, data is a MarketingPreferenceOptIn object as would be returned from the marketingPreferenceOptIn operation

marketing_preference_opt_in.updated: When a marketing preference opt-in is updated

Memberships

In the following events, data is a Membership object as would be returned from the listMemberships operation

membership.cancelled: When a membership is cancelled
membership.charged: When a membership is charged
membership.confirmed: When a membership is confirmed
membership.expired: When a membership expires

Get started

1. Create a handler

Set up a publicly accessible HTTPS endpoint that can accept webhook requests with a POST method. Your endpoint function should quickly return a 2xx HTTP status code, as slow-running requests may cause the webhook to be marked as failed.

2. Register your endpoint

Add your URL, set a secret key, and choose which events to listen out for.

Once you have added the required settings you can click 'Enable' to start receiving webhooks.

Securing your endpoint

The secret key that you entered in the webhook configuration (above) is used to generate a unique signature for each webhook sent to your servers. You should use this signature to verify that webhooks originated in Trybe and discard any that do not match the required signature.

The signature header included in each webhook is a SHA-256 hash of the webhook payload. To verify the signature you should:

Create a SHA-256 hash of the entire request body using your secret key
Compare your generated signature with the one received in the signature header

Webhooks for multiple sites

If you are working with a Trybe setup that includes multiple sites (locations) and want to receive webhooks for all of them, you'll need to create a webhook configuration for each site.

The important exception to this is for customer-related events: in Trybe, customers are associated with a 'Brand', which is a collection of one or more sites. If you want to receive webhooks for customer-related events across the brand, you only need to register a webhook for one site in the brand. Get in touch with Trybe support if you're not sure about the site and brand setup you are working with.

Retries

If the webhook is not able to be delivered or receives an HTTP status that isn't in the 2xx range it will be resent after a short delay.

An erroring webhook event will be tried up to 3 times before it is marked as failed.

Best practices for using webhooks

Verify event signatures

Always check the signature header to verify that webhooks were sent from Trybe, as described above.

Quickly return a 2xx response

Your endpoint must quickly return a successful status code (2xx) before carrying out any complex logic that could cause a timeout.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the IDs you’ve processed, and then not processing already-logged events.

Only listen to event types your integration requires

Configure your webhook endpoints to only receive the types of events your integration requires. Listening for additional events (or all events) isn't recommended as it will put undue strain on your server.

Handle events asynchronously

Configure your handler to process incoming events on an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries might overwhelm your endpoint hosts.

Asynchronous queues allow you to process the concurrent events at a rate your system can support.

Exempt webhook route from CSRF protection

Your site might automatically check that every POST request contains a CSRF token. This is an important security feature that helps protect you and your users from cross-site request forgery attempts. However, this security measure might also prevent your site from processing legitimate webhook events. If that's the case you might need to exempt the webhooks route from CSRF protection.