1. Overview

doo provides a way to synchronize doo entities to external systems using webhooks. Webhooks are user-defined HTTP callbacks. Each time an entity is changed will call the respective endpoint of the external system.

Webhooks configurations will be attached to an entire organization with all its events. The payload of event and order webhooks will contain the event_id so you can decide which webhooks to process.

Basic webhook flow

1. A user creates/edits/remove an entity in doo, which fires one or more triggers

2. For each trigger, if an external webhook endpoint has been configured

   1. doo authenticates with the external authorization endpoint to retrieve an access token (optional)

   2. doo sends a POST request (optionally authorized) to the external endpoint with the entity in a payload

   3. external system processes webhook payload as required

Typical system setup

A typical integration scenario consists of the customer's Content Management System (CMS), which uses doo widgets to enable attendees to book, and the customer's Customer Relationship Management (CRM) as an external system, which provides endpoints for doo webhooks (authorization, event, and order).

2. Setup guide

If webhooks are part of your doo package, please follow the checklist below and provide the necessary details to your operational doo counterpart or to support@doo.net:

1. Contact doo

   1. (optional) we will provide you a test account and set up webhooks with an https://requestb.in integration (or any other similar service). In this way, you will be able to check how the webhooks work and see all the real payload from them

2. Implement OAuth endpoint to secure your endpoints and allow doo to authorize with your system before sending webhooks (optional, more)

   1. Provide <client_secret>

   2. Provide OAuth endpoint URL (<external_oauth_endpoint_url>)

3. Implement endpoints to receive webhook payload for each needed entity and trigger (more)

   1. Provide a list of required triggers and endpoint URLs for them (e.g. <trigger_name> - <external_webhook_endpoint_url>)

3. Technical specification

3.2. Authorization endpoint (to be provided by an external system) 

Webhooks OAuth Endpoint

3.3. Webhook endpoints (to be provided by an external system) 

Curl example of the webhook HTTP POST request to external endpoint: 

curl -H "Content-Type:application/json" \
-H "Accept:application/json" \
-H "authorization:Bearer <access_token>" \
-X POST -d '<webhook_payload_json>' \
<external_webhook_endpoint_url>

• <access_token> - should be provided by the external system for doo (before every webhook push to the external endpoint, optional)

• <webhook_payload_json> - payload object provided by doo

• <external_webhook_endpoint_url> - should be provided by the external system for doo (once)

The payload which doo will send with each webhook request depends on the entity: 

• Event - EventsIdEditGetResponse model

• Order - OrdersIdGetResponse model

• Attendee -

• Contact -

Use External HTTP response rules to share the status of webhook processing with doo

3.4. Webhook payload

3.4.1 Entity identification

Use these IDs in order to identify if a webhook refers to the same entity:

Event

• EventsIdEditGetResponse model → id and OrdersIdGetResponse model → event → id

• Available ticket categories

  • OrdersIdGetResponse model → ticket_categories → id

Order

• OrdersIdGetResponse model → order_details → id

Attendee

• OrdersIdGetResponse model → order_details → attendees → id

• Ticket

  • OrdersIdGetResponse model → order_details → attendees → ticket → checkin_link
    e.g. https://doo.net/checkin/MuxX67FF

  • use the ticket hash (in this example: MuxX67FF) in the "checkin_link" to check-in a ticket: /wiki/spaces/API/pages/18088181

  • Ticket category

    • OrdersIdGetResponse model → order_details → attendees → ticket → event_ticket_id

3.4.2 Entity statuses

Event

• EventsIdEditGetResponse model → status

• Possible values:

  • draft: event has not been published yet

  • live: event has been published

  • cancelled: event has been cancelled

  • done: event has been published and the event end date has passed

  • deleted: draft event has been deleted

Order

• OrdersIdGetResponse model → order_details → status

• Possible values:

  • active: order is valid, but may not have been fully paid yet; refer to attendee or ticket status

  • organizer_accepted_cancellation: order has been cancelled

  • pending_organizer_approval: order is waiting for approval by the organizer

  • pending_organizer_review: order is waiting for approval by the organizer and has been flagged by the organizer

  • denied: order has been rejected by the organizer

  • removed: order has been removed from the system

  • attendee_accepted_cancellation: when booker cancels the order for a free event from booking portal

Attendee

• OrdersIdGetResponse model → order_details → attendees → status

• Possible values:

  • active: attendee has successfully registered and paid

  • inactive: otherwise

• Ticket

  • OrdersIdGetResponse model → order_details → attendees → ticket → status

  • Possible values:

    • pending: ticket is pending approval or payment

    • valid: ticket is valid

    • cancelled: ticket has been cancelled

    • checked: ticket has been valid and has been checked-in

3.4.3 Entity data

Order

• Booker

  • OrdersIdGetResponse model → order_details
    details such as first_name, last_name, email etc

  • OrdersIdGetResponse model → order_details → buyer_answers
    answers to booker-level event questions

• Attendees

  • OrdersIdGetResponse model → order_details → attendees
    details such as first_name, last_name, email etc

  • OrdersIdGetResponse model → order_details → attendees → answers
    answers to attendee-level event questions

Notes:

1. If you have an event with only booker-level questions (and no attendee-level questions), all details and answers will be returned in "order_details" and "buyer_answers". "order_details → attendees" will be empty except for an "id", "status" and a "ticket" object.

2. If you want to retrieve the answer of a buyer or an attendee to a specific question, look for the answer object with the relevant "question" value (string-match the question value)

Event

• Prices

  • EventsIdEditGetResponse model → ticket_categories → buyer_price

    • for both events with net and gross ticket prices: the price which buyer will pay for the ticket with all the fees and VAT

  • EventsIdEditGetResponse model → ticket_categories → display_price

    • in case of event with net ticket prices: the price which is shown on the event website/widget as the price of one ticket without any fees and VAT

    • in case of event with gross ticket prices: the price which is shown on the event website/widget as the price of one ticket with VAT but without fees

3.6. Binding to entities from an external system 

doo supports binding its entities to entities from the external system:

1. Event from doo can be bound to a user from an external system

   • For each user in doo, we can configure an external user ID and it will be included in the event payload (EventsIdEditGetResponse object, external_user_id property in the root scope of the JSON object)

2. Booker from doo can be bound to a customer from an external system

   1. A customer ID can be passed from the external CRM to doo via prefill in the widget snippet or through doo email campaigns (see more details in Widgets)

   2. doo will pass the ID back to the external system in webhooks (OrdersIdGetResponse object, external_customer_id in the root scope of the JSON object)

To get more information about bindings, contact doo (kundenservice@doo.net)