Yoozrr

Outline

1. Overview
2. PortalCompanyWebhook Fields
   • Required vs Optional
   • Field Descriptions
3. Webhook Types
4. AppendTypes
5. Authentication Types (authType)
   • NONE
   • BASIC
   • BEARER
   • HMAC
   • JWT
   • JWE
   • CUSTOM_HEADERS
   • Key Usage for Each Type
   • Special Note on JWT
6. Public Key Endpoint
7. Example Webhook Object

1. Overview

Outbound data can only be set via portalCompany. If you need a global outbound hook, you'll need to use Integration Webhook explained here. The key difference is this is related to specific portal companies where it will trigger.

PortalCompanyWebhooks allow you to configure outbound webhooks that are triggered by specific events (the "WHEN") for a given portal company (the "WHAT"), and define how the data is delivered and authenticated (the "HOW"). This system is designed for scenarios where you need to notify external systems or services about changes or activities related to a particular portal company, such as booking updates, job status changes, or trip events.

• WHAT: The webhook object defines what data will be sent via the appendTypes ([WebhookAppendTypes]) allow you to include additional related data in the webhook payload, such as information about bookings, jobs, trips, or vouchers, depending on your integration needs. Understand Booking, Jobs, Trips and Legs more here.
• WHEN: The types field ([WebhookType]) specifies the events that will trigger the webhook. These include actions like BOOKING_CREATED, JOB_END, TRIP_START, INVOICE_APPROVED, and more. Each time one of these events occurs for the portal company, the webhook will be triggered.
• HOW: The deliveryType field determines how the webhook is sent (HTTP, SFTP, EMAIL), and the data field contains the configuration for that delivery method. Authentication is handled via the authType and key fields, supporting various methods such as JWT, HMAC, or none.

In summary, PortalCompanyWebhooks provide a flexible way to automate outbound notifications for specific portal company events, with customizable delivery and security options.

2. PortalCompanyWebhook Fields

3. WebhookDeliveryTypes and Required Fields

Note: For EMAIL, the to field can be a single email or a comma-separated list of emails (e.g., "to": "a@example.com,b@example.com").

4. Webhook Types

The types field ([WebhookType]) specifies the events that will trigger the webhook. Each webhook can listen to one or more event types. When any of the specified events occur for the associated portal company, the webhook will be triggered and the configured payload will be delivered.

Available Webhook Types:

LEG_ACTIVITY

LEG_PLAN_START

LEG_START

LEG_START_OUT

LEG_PLAN_END

LEG_END

LEG_END_OUT

TRIP_START

TRIP_END

JOB_START

JOB_END

REQUEST_FOR_COLLECTION

BOOKING_CREATED

BOOKING_UPDATED

BOOKING_STATUS_CHANGED

INVOICE_CREATED

INVOICE_UPDATED

INVOICE_STATUS_CHANGED

INVOICE_APPROVED

Usage:

Set the types array to the list of events you want this webhook to listen for. For example, to trigger on booking creation and updates:

"types": ["BOOKING_CREATED", "BOOKING_UPDATED"]

5. AppendTypes

The appendTypes field ([WebhookAppendTypes]) allows you to include additional related data in the webhook payload. When specified, the system will fetch and append the corresponding data objects to the payload before delivery. This is useful for enriching the webhook with more context about the event.

Available AppendTypes:

• BOOKING
• JOB
• TRIP
• LEG
• VOUCHER
• VOUCHER_ITEM
• COST_ITEM

Usage:

Set the appendTypes array to the list of related entities you want included in the payload. For example, to include both booking and job data:

"appendTypes": ["BOOKING", "JOB"]

The appended data will be added to the payload under camelCase keys matching the append type (e.g., booking, job).

6. Authentication Types (authType)

NONE

• Description: No authentication. No key required.
• Use Case: Public endpoints or internal testing.

BASIC

• Description: HTTP Basic Auth. data.headers.Authorization must be set.
• Key: Not used.

BEARER

• Description: Bearer token in Authorization header. data.headers.Authorization must be set.
• Key: Not used.

HMAC

• Description: HMAC-SHA256 signature is generated using the key as the secret.
• Key: Required. Used as the HMAC secret.

JWT

• Description: JWT is generated and signed for the webhook request.
• Key:
  • If provided and starts with -----BEGIN ...PRIVATE KEY-----: Treated as a PEM-encoded RSA private key. The system will use this key to sign the JWT using the RS256 algorithm.
    
  • If provided and does not start with : Treated as a symmetric shared secret. The system will use this key to sign the JWT using the HS256 algorithm.
  • If blank: The system will use its own private key to sign the JWT using the RS256 algorithm. The corresponding public key can be fetched via the portalCompanyWebhooksPublicKey GraphQL query.
• Benefit: Allows secure, verifiable requests. You can control signing (with your own shared secret) or rely on the system’s asymmetric key pair.

JWE

• Description: Payload is encrypted using a JWK public key.
• Key: Required. Must be a stringified JWK public key (RSA, use: 'enc').
• Benefit: Ensures only the intended recipient can decrypt the payload.

CUSTOM_HEADERS

• Description: Custom headers are sent as specified in data.headers.
• Key: Not used.

Key Usage Table

Special Note on JWT

• If you provide a key, it must be a PEM-encoded private key string. The system will use this to sign JWTs.
• If you do not provide a key, the system will use its own private key. The corresponding public key for verification can be fetched via the portalCompanyWebhooksPublicKey GraphQL query.

Public Key Endpoint

To fetch the system’s public key for JWT verification, use the following GraphQL query:

query {
  portalCompanyWebhooksPublicKey {
    publicKey
  }
}

Example Webhook Object

{
  "_id": "661f1e1e1e1e1e1e1e1e1e1e",
  "portalCompanyUuid": "db72f304-1cd7-4731-83f4-e6ab0bff9ba5",
  "baseCompanyUuid": "8f90b01f-362d-4b27-800f-ab7f410b81c8",
  "name": "Order Created Webhook",
  "deliveryType": "HTTP",
  "data": {
    "url": "https://example.com/webhook",
    "method": "POST",
    "headers": { "Content-Type": "application/json" }
  },
  "types": ["BOOKING_CREATED"],
  "appendTypes": ["BOOKING"],
  "authType": "JWT",
  "key": "", // blank means use system private key
  "convertFunction": "return { ...payload, extra: true }"
}