Applications

Applications are the primary way to interact with HappyColis GraphQL APIs. The platform is modular and extensible — you integrate your existing systems by registering an application that connects to one or more organizations through the API.

Application Types

Type	Visibility	Installation
PRIVATE	Restricted to a predefined list of organizations	Organization list managed internally by HappyColis
PUBLIC	Listed on the HappyColis app page	Installable by any registered organization via OAuth

Public applications are installed through an OAuth 2.0 authorization grant flow, initiated by the organization's administrator. Private applications receive their credentials directly through the HappyColis dashboard.

---

Security

Each registered application receives:

• client_id and client_secret — used exclusively for server-to-server communication. Never expose these on the client side.
• integration_token — issued per organization through the authentication grant flow. This token carries the permissions granted by the organization administrator.

For PRIVATE applications, the integration_token is displayed in the application details page within the HappyColis dashboard.

To call the GraphQL API, include the integration_token as a Bearer token:

Authorization: Bearer YOUR_INTEGRATION_TOKEN

See Authentication for full details on token management, refresh flows, and scopes.

---

Public Applications — OAuth Flow

Public applications obtain an integration_token through the OAuth 2.0 authorization code grant.

Step 1: Redirect to Authorization Page

Redirect the user to the HappyColis authorization page with the following query parameters:

Parameter	Description
scope	Comma-separated list of permissions your application requires
organization	Organization ID the application will be installed to
client_id	Your application's client identifier
state	Random string for CSRF protection — returned unchanged in the callback
redirectUri	URL where HappyColis redirects after authorization

Step 2: Handle the Callback

If the user grants access, HappyColis redirects to your redirectUri with two parameters:

• code — Authorization code to exchange for an integration_token
• hmac — SHA-256 hash of the query parameters signed with your client_secret, base64-encoded

The HMAC is computed over the parameters in alphabetical order: client_id, code, organization, redirectUri, scope, state.

WARNING

Always verify the HMAC signature before processing the authorization code to ensure the callback was not tampered with.

Step 3: Exchange Code for Token

Call the access-token endpoint with the authorization code to receive the integration_token. Store it securely — you will use it for all subsequent API calls on behalf of the organization.

Flow Diagram

---

Requesting New Permissions

If your application needs additional permissions, add the new scopes to the scope parameter. The user will be prompted to grant them the next time they open your application.

---

Embedding Applications

PUBLIC applications can embed their UI directly within the HappyColis interface. Contact our support team for documentation on the embedding process.

---

Subscribing to Events

HappyColis is an event-driven platform. Subscribe to events using the applicationWebhookSubscribe mutation:

mutation ApplicationWebhookSubscribe(
  $input: ApplicationWebhookSubscribeInput!
) {
  applicationWebhookSubscribe(input: $input) {
    id
    type
    health
    endPoint
    active
  }
}

Webhook Delivery

Webhooks are delivered as HTTP POST requests to the endPoint specified in the subscription input. A response with a 2xx status code is considered successful delivery.

Message Format

Each webhook message contains a header and a body:

Header:

{
  "id": "WEBHOOK_ID",
  "type": "WEBHOOK_TYPE",
  "timestamp": "WEBHOOK_TIMESTAMP",
  "organization": "ORGANIZATION_ID",
  "application": "APPLICATION_ID"
}

The body contains event-specific data. See Webhooks for the full list of event types and payload schemas.

HMAC Verification

Every webhook includes an X-HAPPYCOLIS-WEBHOOK-HMAC HTTP header containing a SHA-256 hash of the raw request body, signed with your application's private key and base64-encoded.

To verify:

1. Compute the SHA-256 HMAC of the raw request body using your application's private key
2. Base64-encode the result
3. Compare it to the X-HAPPYCOLIS-WEBHOOK-HMAC header value

TIP

Always verify the HMAC before processing webhook payloads to ensure message integrity and authenticity.