Skip to content

Webhooks

Note

This functionality is exclusively accessible with paid subscriptions. Verify whether your plan includes this feature, upgrade if necessary, or reach out to us for assistance.

When incorporating Oveit integrations, you may want your applications to promptly
receive events as they transpire in your Oveit accounts. This allows your backend
systems to execute corresponding actions.

To activate webhook events, the process involves registering webhook endpoints. Once
registered, Oveit can push real-time event data to the designated webhook endpoint of
your application whenever events occur in your Oveit account. Oveit utilizes HTTPS to
transmit webhook events to your app, delivering them in the form of a JSON payload
that encompasses an event object.

Receiving webhook events proves particularly beneficial for monitoring asynchronous
occurrences, such as when an order is placed, an attendee completes a registration form,
or an invoice is issued.

Event Overview

Oveit produces event data that we can transmit to keep you informed of activities within
your account. Each time an event takes place, Oveit generates a new event object (see below).

By enlisting webhook endpoints in your Oveit account, you empower Oveit to
autonomously dispatch event objects via POST requests to the designated webhook
endpoint hosted by your application. Once your webhook endpoint receives the event,
your application can execute backend actions, such as invoking your CRM APIs to store
customer information upon receiving an "order.create" event.

Event Trigger Event object
order.create When a placed order is completed order (see below)
ticket.create When a ticket is issued ticket (see below)
ticket.update When a registration form is changed ticket (see below)

Let's get started

Log in to your account and navigate to the Webhooks section within the Apps panel. From there, you can create a new webhook by entering your webhook callback URL and choosing the events you wish to monitor.

Ensure the Security of Your Webhooks

Once you've confirmed that your webhook endpoint connection functions as expected,
enhance the security of the connection by implementing best practices outlined in the
section below.

One crucial best practice involves using webhook signatures to validate that Oveit
generated the webhook request and that it didn't originate from a server posing as
Oveit.

Event Delivery Behaviors

Retry Behavior

Oveit makes attempts to deliver a specific event to your webhook endpoint for up to 2
days at intervals of 1 minute, 10 minutes, 30 minutes, 1 hour, 2 hours, 6 hours, 12 hours,
18 hours, 24 hours, 36 hours, 48 hours, or until the endpoint responds with a 200 HTTP
status code.

Disable Behavior

Oveit endeavors to notify you of a misconfigured endpoint via email if the endpoint
hasn't responded with a 200 HTTP status code for multiple consecutive days and also it will be automatically disabled.

Best Practices for Using Webhooks

Handle Duplicate Events

Webhook endpoints may occasionally receive the same event more than once. One
approach is to log the events you've processed and avoid processing events that have
already been logged. Every event has an unique uuid identifier.

Only Listen to Event Types Your Integration Requires

Configure your webhook endpoints to receive only the necessary event types for your
integration. Listening to extra events (or all events) can strain your server unnecessarily,
and it is not recommended.

Receive Events with an HTTPS Server

If you use an HTTPS URL for your webhook endpoint, Oveit validates that the connection
to your server is secure before transmitting your webhook data. Your server must be
properly configured to support HTTPS with a valid server certificate for this to work.

Verify Events Are Sent from Oveit

Authenticate the origin of received events from Oveit by confirming webhook signatures. Oveit secures webhook events sent to your endpoints by appending two headers to each event: a signature header named Oveit-WH-Signature and a timestamp header named Oveit-WH-Signature-Timestamp. This setup enables you to validate the authenticity of the events, ensuring they are genuinely dispatched by Oveit and not manipulated by a third party.

To verify, generate an HMAC (Hash-based Message Authentication Code) signature. This process involves hashing a combination of the payload and timestamp using the webhook secret key from the Dashboard. As the timestamp is a crucial element of the signed payload, any tampering by an attacker would invalidate the signature. If the signature is correct but the timestamp is excessively outdated, your application retains the option to reject the payload. Consider allowing a tolerance of 5 to 10 minutes between the timestamp and the current time.

Retrieve Your Endpoint's Secret

Navigate to the Webhooks section of the Dashboard. Choose the specific endpoint for
which you want to acquire the secret and locate the secret.
Oveit generates a distinctive secret key for each endpoint. In case you utilize multiple
endpoints, you need to procure a secret for each one that requires signature
verification. Oveit then begins signing each webhook it dispatches to the respective
endpoint.

Event Object

{
  "data": {

  },
  "version": "1.0",
  "event_id": "54d6f3cc-6901-4897-8b89-6fa3cb9f8419",
  "event_type": "ticket.create"
}

Order Data Object

{
    "order": {
    "id": 1,
    "uuid": "e0847e21-21ab-4096-89ae-3819fd42026e",
    "date": "2024-01-10T18:48:51+02:00",
    "date_formatted": "Jan 10, 2024, at 18:48",
    "language": "en",
    "currency": "USD",
    "payment_processor": null,
    "status": "Completed",
    "is_canceled": false,
    "pending_reason": null,
    "email": "developer@oveit.com",
    "items": [
      {
        "name": "Event with Registration Form (VIP Ticket)",
        "quantity": "2",
        "currency": "USD",
        "type": "ticket",
        "price_without_tax": "8.40",
        "price_tax": "3.19",
        "fee_without_tax": "0.84",
        "fee_tax": "0.32",
        "discount": "0.00",
        "final_price": "11.00",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        }
      },
      {
        "name": "Mango",
        "quantity": "3",
        "currency": "USD",
        "type": "addon",
        "price_without_tax": "8.40",
        "price_tax": "4.79",
        "fee_without_tax": "0.84",
        "fee_tax": "0.48",
        "discount": "0.00",
        "final_price": "11.00",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        }
      },
      {
        "name": "Shirt",
        "quantity": "3",
        "currency": "USD",
        "type": "addon",
        "price_without_tax": "16.81",
        "price_tax": "9.58",
        "fee_without_tax": "1.68",
        "fee_tax": "0.96",
        "discount": "0.00",
        "final_price": "22.00",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        }
      },
      {
        "name": "Hat",
        "quantity": "8",
        "currency": "USD",
        "type": "addon",
        "price_without_tax": "12.61",
        "price_tax": "19.16",
        "fee_without_tax": "1.26",
        "fee_tax": "1.92",
        "discount": "0.00",
        "final_price": "16.50",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        }
      },
      {
        "name": "Virtual wallet credit (VIP Ticket)",
        "quantity": "1",
        "currency": "USD",
        "type": "wallet_credit",
        "price_without_tax": "84.03",
        "price_tax": "15.97",
        "fee_without_tax": "0.00",
        "fee_tax": "0.00",
        "discount": "0.00",
        "final_price": "100.00",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        }
      },
      {
        "name": "Virtual wallet credit (VIP Ticket)",
        "quantity": "1",
        "currency": "USD",
        "type": "wallet_credit",
        "price_without_tax": "16.81",
        "price_tax": "3.19",
        "fee_without_tax": "0.00",
        "fee_tax": "0.00",
        "discount": "0.00",
        "final_price": "20.00",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        }
      }
    ],
    "customer": {
      "name": "Oveit Developer",
      "is_company": false,
      "tax_code": null,
      "address": "115 Wild Basin Rd. S Ste 307",
      "city": "Austin",
      "state": "Texas",
      "state_code": "TX",
      "country": "United States",
      "country_code": "US"
    },
    "customer_form": [
      {
        "name": "Type",
        "value": "Online"
      }
    ],
    "tickets": [
      {
        "code": "9bab7e36",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        },
        "series": "DDD 16",
        "seat": null,
        "registration_form": [
          {
            "name": "Name",
            "value": "Oveit Attendee"
          },
          {
            "name": "Position",
            "value": "Developer"
          }
        ],
        "wallet_credit": {
          "amount": "100.00",
          "currency": "USD"
        },
        "addons": [
          {
            "name": "Beer",
            "uses": 2
          },
          {
            "name": "Mango",
            "uses": 2
          },
          {
            "name": "Shirt",
            "uses": 1
          },
          {
            "name": "Hat",
            "uses": 5
          }
        ]
      },
      {
        "code": "958f5916",
        "event": {
          "name": "Event with Registration Form",
          "hash": "e3aefd2bf9",
          "location": "Studio4",
          "has_venue": false,
          "starts_at": null,
          "ends_at": null,
          "is_perpetual": true
        },
        "ticket_type": {
          "name": "VIP Ticket",
          "has_nft": false,
          "is_seatless": false
        },
        "series": "DDD 17",
        "seat": null,
        "registration_form": [
          {
            "name": "Name",
            "value": "Oveit Attendee2"
          },
          {
            "name": "Position",
            "value": "Developer"
          }
        ],
        "wallet_credit": {
          "amount": "20.00",
          "currency": "USD"
        },
        "addons": [
          {
            "name": "Beer",
            "uses": 2
          },
          {
            "name": "Mango",
            "uses": 1
          },
          {
            "name": "Shirt",
            "uses": 2
          },
          {
            "name": "Hat",
            "uses": 3
          }
        ]
      }
    ],
    "invoice": [
      {
        "name": "Invoice - Oveit Developer - Nr. OVEIT 001",
        "number": "OVEIT 1",
        "items": [
          {
            "name": "Event with Registration Form (VIP Ticket)",
            "quantity": 2,
            "currency": "USD",
            "unit_net_price": "8.40",
            "unit_tax_price": "1.60",
            "total_price": "20.00"
          },
          {
            "name": "Mango",
            "quantity": 3,
            "currency": "USD",
            "unit_net_price": "8.40",
            "unit_tax_price": "1.60",
            "total_price": "30.00"
          },
          {
            "name": "Shirt",
            "quantity": 3,
            "currency": "USD",
            "unit_net_price": "16.81",
            "unit_tax_price": "3.19",
            "total_price": "60.00"
          },
          {
            "name": "Hat",
            "quantity": 8,
            "currency": "USD",
            "unit_net_price": "12.61",
            "unit_tax_price": "2.39",
            "total_price": "120.00"
          },
          {
            "name": "Virtual wallet credit (VIP Ticket)",
            "quantity": 1,
            "currency": "USD",
            "unit_net_price": "84.03",
            "unit_tax_price": "15.97",
            "total_price": "100.00"
          },
          {
            "name": "Virtual wallet credit (VIP Ticket)",
            "quantity": 1,
            "currency": "USD",
            "unit_net_price": "16.81",
            "unit_tax_price": "3.19",
            "total_price": "20.00"
          },
          {
            "name": "Online processing fee",
            "quantity": 1,
            "currency": "USD",
            "unit_net_price": "19.33",
            "unit_tax_price": "3.67",
            "total_price": "23.00"
          }
        ],
        "statements": [
          "VAT exempt, according to Directive 2006/112/EC"
        ],
        "download_link": "https://l.oveit.com/orders/download_invoice",
        "currency": "USD",
        "net_price": "313.45",
        "tax_price": "59.55",
        "total_price": "373.00",
        "is_canceled": false,
        "is_paid": true,
        "is_reversed": false,
        "is_reverse": false,
        "status": "paid"
      }
    ]
  }
}

Ticket Data Object

{
  "ticket": {
    "code": "958f5916",
    "seat": null,
    "event": {
      "hash": "e3aefd2bf9",
      "name": "Event with registration form",
      "ends_at": null,
      "location": "Studio4",
      "has_venue": false,
      "starts_at": null,
      "is_perpetual": true
    },
    "addons": null,
    "series": "DDD 17",
    "ticket_type": {
      "name": "VIP Ticket",
      "has_nft": false,
      "is_seatless": false
    },
    "wallet_credit": null,
    "registration_form": [
      {
        "name": "Name",
        "value": "Oveit Attendee2"
      },
      {
        "name": "Position",
        "value": "Developer"
      }
    ]
  }
}