Glossary
Definitions for the key terms used across the HappyColis webhook documentation and codebase.
Application
A registered third-party service that connects to HappyColis. An Application is created by a Partner and holds the OAuth credentials (clientId, clientSecret) used for authentication.
Every webhook delivery is signed using the clientSecret of the Application that owns the integration.
Entity: ApplicationEntity (application table) Key fields: clientId, clientSecret, callbackUrl, scopes, status
Client ID / Client Secret
Credentials issued to an Application at registration time.
- Client ID (
clientId) — a public identifier for the application. - Client Secret (
clientSecret) — a private key used to sign webhook payloads (HMAC-SHA256) and to obtain OAuth tokens. Treat it like a password.
See Signature Verification for how to use the secret to verify incoming webhooks.
Integration
A link between an Application and an Organization. When an organization installs an application, an Integration record is created. The Integration holds the authorized scopes and the token (if issued).
Each Integration has exactly one Queue through which all its webhook messages flow.
Entity: IntegrationEntity (gb_integration table) Key fields: appId, organizationId, scopes, status, tokenIntegration type value: INTEGRATION
OAuth Client
An alternative connection mode where an application uses the OAuth 2.0 client credentials flow instead of a long-lived integration token. An OAuth client still authenticates with a clientId / clientSecret pair but operates as a short-lived session.
From the queue's perspective, an OAuth client is handled identically to an Integration — it gets its own per-integration queue and uses the same delivery pipeline.
Integration type value: OAUTH_CLIENT
Organization
A tenant on the HappyColis platform — typically a merchant or logistics operator. Resources such as orders, stock references, delivery orders, and shipments are all scoped to an organization via organizationId.
When a domain event fires, the platform looks up all webhook subscriptions for that organization and event type, then enqueues a message for each matching subscriber.
organizationId is always present in the webhook message header.
Partner
The company or entity that publishes an Application on HappyColis. Partners are identified by name and hold contact/business metadata.
Entity: PartnerEntity (gb_partner table)
Queue
A per-integration FIFO buffer that serializes webhook delivery. There is exactly one queue per integration (one per integrationId + integrationType combination).
The queue has two properties:
| Property | Values | Meaning |
|---|---|---|
status | HEALTHY / BLOCKED | Whether the last delivery succeeded |
state | READY / LOCKED | Whether a delivery attempt is in flight |
When delivery fails, the queue enters BLOCKED status and no further messages are dispatched until it is manually unblocked.
Entity: IntegrationQueueEntity (gb_integration_queue table)
Queue Item (Message)
A single pending webhook delivery. A queue item is created when QueueProcessor.process() receives an event, and deleted once delivery succeeds. If delivery fails, the item is retained and updated with lastTriedAt and lastErrorMessage.
Entity: IntegrationQueueMessageEntity (gb_integration_queue_message table) Key fields: queueId, webhookId, body, date, retries, lastTriedAt, lastErrorMessage
Topic
A Kafka topic that carries domain events between microservices. The apps microservice consumes all ORGANIZATION_TOPICS via NotificationProcessorController. Each topic is mapped to a WebhookType by a WebHookFormatterInterface implementation.
Internal Kafka topics used by the delivery pipeline:
| Topic | Purpose |
|---|---|
applications.message.process | Trigger delivery of a queue item |
applications.message.processed | Confirm successful delivery |
applications.message.failed | Report a failed delivery attempt |
Webhook Subscription
A record that links an Integration to an event type and a target endpoint. When an event matching organizationId + type fires, a delivery is attempted to the subscription's endPoint.
Each integration may have at most one active subscription per event type.
Entity: IntegrationWebhookEntity (gb_integration_webhook table) Key fields: integrationId, integrationType, organizationId, type, endPoint, headers, health
Webhook Health
Indicates whether recent deliveries to a subscription's endpoint have been successful.
| Value | Description |
|---|---|
HEALTHY | All recent deliveries succeeded. |
FAILING | One or more deliveries failed. The queue is blocked. |
The health field is visible on IntegrationWebhookEntity and returned by the GraphQL API.
Webhook Type
The string identifier for a specific event category. Used when creating a subscription and included in every webhook message header as type.
Examples: order/created, shipment/shipping_event, stock_reference/movement_created.
The full list is defined in WebhookType (apps/apps/src/domain/webhook-type.enum.ts). See the Overview for a complete reference table.
HMAC Signature
A cryptographic signature computed over the full webhook JSON body using HMAC-SHA256 and the application's clientSecret. Sent in the x-happycolis-webhook-signature HTTP header with every delivery.
Use this to verify that requests to your endpoint genuinely originate from HappyColis. See Signature Verification.
See Also
- Overview — architecture and event types
- Signature Verification — verifying webhook authenticity
- Subscription Management — creating and removing subscriptions
- Error Handling and Retries — queue failure behavior and recovery