Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import {
ArrayMaxSize,
ArrayMinSize,
IsArray,
IsBoolean,
IsIn,
IsInt,
IsOptional,
IsString,
IsUrl,
Max,
MaxLength,
Min,
MinLength,
ValidateIf,
} from 'class-validator';
import { Expose, plainToInstance } from 'class-transformer';
import { Webhook } from '../entities/webhook.entity';
import { MAX_CONDITIONS } from '../filters/filter-types';
import type { FilterOperator, WebhookFilters } from '../filters/filter-types';
import { IsValidWebhookFilters } from '../filters/filter-validation';
import { IsHeaderMap } from './is-header-map.validator';
import { ToStrictArray, ToStrictBoolean, ToStrictNumber, ToStrictString } from '../../../common/utils/strict-boolean';
import { MaxCodePoints } from '../../../common/validation/max-code-points';
/**
* Swagger metadata for the smart-filter shape — `WebhookFilters` in filters/filter-types.ts is a
* plain interface (validated at runtime by @IsValidWebhookFilters), which the scanner cannot
* introspect: without these classes the `filters` field on every webhook DTO degraded to a bare
* `{ "type": "object" }` in openapi.json, describing NEITHER side of the wire. Metadata only —
* no validators here; the runtime types stay authoritative.
*/
class WebhookFilterConditionDto {
@ApiProperty({ example: 'sender', description: 'Filterable field for the fired event family.' })
field!: string;
@ApiProperty({ enum: ['is', 'isNot', 'contains', 'equals'], example: 'is' })
operator!: FilterOperator;
@ApiProperty({
oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }, { type: 'boolean' }],
example: ['[email protected]'],
})
value!: string | string[] | boolean;
@ApiPropertyOptional({ description: 'Only meaningful for text fields. Defaults to false.' })
caseSensitive?: boolean;
}
class WebhookFiltersDto {
@ApiProperty({
type: [WebhookFilterConditionDto],
maxItems: MAX_CONDITIONS,
description:
'Every condition must match (AND) for the webhook to fire. An empty list means no filter: the webhook fires on every subscribed event.',
})
conditions!: WebhookFilterConditionDto[];
}
const FILTERS_API_DESCRIPTION =
'Optional smart pre-filter. When set, every condition must match (AND) for the webhook to fire. Omit or null to fire on every subscribed event.';
// An update applies `filters` only when the field is present, so omission keeps the stored filter.
const UPDATE_FILTERS_API_DESCRIPTION =
'Optional smart pre-filter. When set, every condition must match (AND) for the webhook to fire. Omit to keep the stored filters; send null or { conditions: [] } to clear them, so the webhook fires on every subscribed event.';
const FILTERS_API_EXAMPLE = {
conditions: [
{ field: 'sender', operator: 'is', value: ['[email protected]'] },
{ field: 'body', operator: 'contains', value: 'invoice' },
],
};
// Reserved: valid webhook subscription targets that are declared but have no engine emit
// source yet. Currently EMPTY — the former occupants (group.join/leave/update) are now
// dispatched by both engines. Kept as a named export so the catalog/emitter drift guard
// can whitelist any future intentionally-undeployed event without changing its imports.
export const WEBHOOK_RESERVED_EVENTS = [] as const;
export const WEBHOOK_EVENTS = [
'message.received',
'message.sent',
'message.ack',
'message.receipt',
'message.failed',
'message.revoked',
'message.reaction',
'message.edited',
'status.received',
'session.status',
'session.qr',
'session.authenticated',
'session.disconnected',
'session.reconnect_loop',
'session.restriction',
'presence.update',
'event.response',
'poll.vote',
'group.join',
'group.leave',
'group.update',
'group.join_request',
'call.received',
'call.accepted',
'call.rejected',
'call.missed',
...WEBHOOK_RESERVED_EVENTS,
] as const;
const WEBHOOK_URL_OPTIONS = { require_tld: false, require_protocol: true, protocols: ['http', 'https'] };
export class CreateWebhookDto {
@ApiProperty({
description: 'Webhook URL to receive events',
example: 'https://your-server.com/webhook',
maxLength: 2048,
})
// require_tld:false allows hostnames without a dot (e.g. http://localhost:3000); the SSRF
// guard still decides whether the host is actually allowed to be delivered to. The scheme is
// required and must be http(s): the defaults also took 'example.com/hook' and 'ftp://...', which
// were stored and then failed every delivery. 2048 is the column width; PostgreSQL refuses a
// longer value on insert with a 500.
@IsUrl(WEBHOOK_URL_OPTIONS)
@MaxCodePoints(2048)
url!: string;
@ApiPropertyOptional({
description:
"Event types to subscribe to. '*' subscribes to all events except `message.receipt`, which must be named explicitly.",
example: ['message.received', 'session.status'],
enum: [...WEBHOOK_EVENTS, '*'],
type: String,
isArray: true,
minItems: 1,
})
@IsOptional()
@ToStrictArray()
@IsArray()
@ArrayMinSize(1)
// Must include '*' (wildcard subscribe-all) alongside the known events.
@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })
events?: string[];
@ApiPropertyOptional({
description:
'Secret key for HMAC signature verification. Never returned by any webhook route; it is used to ' +
'compute the `X-OpenWA-Signature: sha256=<hex>` header on every delivery.',
// Both bounds are spelled out because @MinLength/@MaxLength do not reach the published schema on
// their own, and the example must satisfy them: the previous 15-character one was rejected by the
// very route that offered it, so pasting it back from Swagger answered 400
// ([#1491](https://github.com/rmyndharis/OpenWA/issues/1491)).
minLength: 16,
maxLength: 255,
example: 'your-webhook-signing-secret',
})
@IsOptional()
@ToStrictString()
@IsString()
// A short secret signs webhooks badly: HMAC-SHA256 over a 4-char key is brute-forcible from one
// observed signature. 16 is the floor, not a recommendation.
@MinLength(16)
@MaxCodePoints(255)
secret?: string;
@ApiPropertyOptional({
description:
'Custom headers to include in webhook requests. Names must be unique ignoring case. Never returned by ' +
'any webhook route. At delivery, `content-type`, `user-agent` and `x-openwa-*` names are stripped so a ' +
'custom header cannot shadow a system one, ' +
'and so are the connection-level names the HTTP client owns (`connection`, `content-length`, ' +
'`expect`, `keep-alive`, `te`, `trailer`, `transfer-encoding`, `upgrade`).',
example: { 'X-Custom-Header': 'value' },
})
@IsOptional()
@IsHeaderMap()
headers?: Record<string, string>;
// `nullable` spelled out for the same reason lastTriggeredAt spells out its type: the field is
// STORED as null whenever a webhook is created without filters (`dto.filters ?? null`), and the
// description offers null as an input, so a schema without it rejects a value the route both
// sends and accepts.
@ApiPropertyOptional({
type: WebhookFiltersDto,
description: FILTERS_API_DESCRIPTION,
example: FILTERS_API_EXAMPLE,
nullable: true,
})
@IsOptional()
@IsValidWebhookFilters()
filters?: WebhookFilters | null;
@ApiPropertyOptional({
description:
'Total delivery attempts per event, including the first (0 and 1 both mean a single attempt with no ' +
'retry). An event that exhausts them is recorded in GET /api/webhooks/delivery-failures; the webhook ' +
'stays active.',
example: 3,
minimum: 0,
maximum: 5,
})
@ToStrictNumber()
@IsOptional()
@IsInt()
@Min(0)
@Max(5)
retryCount?: number;
}
export class UpdateWebhookDto {
@ApiPropertyOptional({ description: 'Webhook URL', maxLength: 2048 })
// Not @IsOptional: that also skips validation for null, which these NOT NULL columns cannot store
// (save() then failed with a 500). Only an omitted field means "leave unchanged".
@ValidateIf((_: UpdateWebhookDto, v: unknown) => v !== undefined)
@IsUrl(WEBHOOK_URL_OPTIONS)
@MaxCodePoints(2048)
url?: string;
@ApiPropertyOptional({
description:
"Event types to subscribe to. '*' subscribes to all events except `message.receipt`, which must be named explicitly.",
enum: [...WEBHOOK_EVENTS, '*'],
type: String,
isArray: true,
minItems: 1,
})
@ValidateIf((_: UpdateWebhookDto, v: unknown) => v !== undefined)
@ToStrictArray()
@IsArray()
@ArrayMinSize(1)
@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })
events?: string[];
@ApiPropertyOptional({
// No `minLength` here, unlike create: this route also accepts the empty string as "clear the
// secret", so a 16 in the schema would reject a value the route honours. The floor still applies
// to every other value, which only the description can say.
description:
'Secret key for HMAC signature. At least 16 characters, or an empty string to clear it. ' +
'Never returned by any webhook route.',
maxLength: 255,
// Deliberately no `example`, unlike create. This route patches a webhook that is already
// signing deliveries, and a prefilled secret submitted whole would replace a working key with
// a published one: every later delivery still verifies, so nothing looks broken while the
// signature is forgeable by anyone reading these docs. The floor belongs in the description
// here, where it costs a `400` to ignore rather than a silent downgrade.
})
@IsOptional()
@ToStrictString()
@IsString()
// Same floor as create: a short secret is brute-forcible from one observed signature. The
// floor is skipped only for the empty string, which this route treats as "clear the secret"
// (the service stores null for it); a non-string value is still rejected by @IsString.
@ValidateIf((o: UpdateWebhookDto) => o.secret !== '')
@MinLength(16)
@MaxCodePoints(255)
secret?: string;
@ApiPropertyOptional({
description: 'Custom headers. Replaces the stored map wholesale. Never returned by any webhook route.',
example: { 'X-Custom-Header': 'value' },
})
@ValidateIf((_: UpdateWebhookDto, v: unknown) => v !== undefined)
@IsHeaderMap()
headers?: Record<string, string>;
// `nullable` spelled out for the same reason lastTriggeredAt spells out its type: the field is
// STORED as null whenever a webhook is created without filters (`dto.filters ?? null`), and the
// description offers null as an input, so a schema without it rejects a value the route both
// sends and accepts.
@ApiPropertyOptional({
type: WebhookFiltersDto,
description: UPDATE_FILTERS_API_DESCRIPTION,
example: FILTERS_API_EXAMPLE,
nullable: true,
})
@IsOptional()
@IsValidWebhookFilters()
filters?: WebhookFilters | null;
@ApiPropertyOptional({ description: 'Enable/disable webhook' })
@ToStrictBoolean()
@ValidateIf((_: UpdateWebhookDto, v: unknown) => v !== undefined)
@IsBoolean()
active?: boolean;
@ApiPropertyOptional({
description:
'Total delivery attempts per event, including the first (0 and 1 both mean a single attempt). Same ' +
'range the create route enforces.',
example: 3,
minimum: 0,
maximum: 5,
})
@ToStrictNumber()
@ValidateIf((_: UpdateWebhookDto, v: unknown) => v !== undefined)
@IsInt()
@Min(0)
@Max(5)
retryCount?: number;
}
/**
* Public response shape for a webhook. Deliberately omits `secret` (the HMAC
* signing key) and `headers` (which may carry receiver credentials) — these are
* write-only and never appear in a response built from this DTO. The backup route
* (`GET /api/infra/export-data`) also omits both from its webhook rows.
*
* `@Expose()` is required on every field: `fromEntity` maps with
* `excludeExtraneousValues: true`, so only exposed fields are serialized and any
* undeclared entity field (secret, headers, the session relation) is dropped.
*/
export class WebhookResponseDto {
@Expose()
@ApiProperty()
id!: string;
@Expose()
@ApiProperty()
sessionId!: string;
@Expose()
@ApiProperty()
url!: string;
@Expose()
// Same vocabulary the create and update bodies validate against: the stored list can only hold
// values those routes accepted. Publishing a bare string[] understated the response, and left
// every client's typed event list comparing against `array<string>` instead of the enum.
@ApiProperty({ enum: [...WEBHOOK_EVENTS, '*'], type: String, isArray: true })
events!: string[];
@Expose()
// `nullable` spelled out for the same reason lastTriggeredAt spells out its type: the field is
// STORED as null whenever a webhook is created without filters (`dto.filters ?? null`), and the
// description offers null as an input, so a schema without it rejects a value the route both
// sends and accepts.
@ApiPropertyOptional({
type: WebhookFiltersDto,
description: FILTERS_API_DESCRIPTION,
example: FILTERS_API_EXAMPLE,
nullable: true,
})
filters?: WebhookFilters | null;
@Expose()
@ApiProperty()
active!: boolean;
@Expose()
@ApiProperty()
retryCount!: number;
@Expose()
// Spelled out because a bare @ApiPropertyOptional() on `Date | null` emits `type: object`, and the
// published schema then rejects both values this field actually carries.
@ApiPropertyOptional({ type: String, format: 'date-time', nullable: true })
lastTriggeredAt?: Date | null;
@Expose()
@ApiProperty()
createdAt!: Date;
@Expose()
@ApiProperty()
updatedAt!: Date;
static fromEntity(entity: Webhook): WebhookResponseDto {
return plainToInstance(WebhookResponseDto, entity, { excludeExtraneousValues: true });
}
static fromEntities(entities: Webhook[]): WebhookResponseDto[] {
return entities.map(entity => WebhookResponseDto.fromEntity(entity));
}
}
/**
* A webhook delivery that exhausted its retries, or one not sent (attempts 0); the shape
* `GET /webhooks/delivery-failures` serves. A shed or shutdown-refused delivery is replayed by the outbox
* sweep; one rejected before sending (an over-cap or unserializable payload) is recorded once and not
* replayed. A later successful delivery removes the row.
*/
export class WebhookDeliveryFailureDto {
@ApiProperty({ example: '0a941dac-a965-45e7-b318-74ae8be134f0' })
id!: string;
@ApiProperty({ example: '0a941dac-a965-45e7-b318-74ae8be134f0' })
webhookId!: string;
@ApiProperty({ example: '0a941dac-a965-45e7-b318-74ae8be134f0' })
sessionId!: string;
@ApiProperty({ example: 'message.received' })
event!: string;
@ApiProperty({ example: 'https://receiver.example.com/hook' })
url!: string;
@ApiPropertyOptional({
type: String,
nullable: true,
description: 'The idempotency key the receiver would have deduped on.',
})
idempotencyKey?: string | null;
@ApiPropertyOptional({ type: String, nullable: true })
deliveryId?: string | null;
@ApiProperty({
description:
'Attempts recorded for the delivery; 0 when it was shed, refused or failed before sending. With the ' +
'queue disabled, a delivery that shutdown caught in a retry backoff also records 0, although earlier ' +
'attempts were sent.',
example: 5,
})
attempts!: number;
@ApiPropertyOptional({
type: Number,
nullable: true,
description: 'Last HTTP status when the failure was a non-2xx response; null for a network/timeout error.',
example: null,
})
lastStatusCode?: number | null;
@ApiProperty({ example: 'fetch failed' })
lastError!: string;
@ApiProperty({ type: String, format: 'date-time', description: 'When the failure was first recorded.' })
createdAt!: Date;
@ApiProperty({
description:
'True when the row still holds the event data and can be replayed with ' +
'`POST /webhooks/delivery-failures/redrive`. Only terminal rows (attempts > 0) recorded while ' +
'`WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0 are, until that window passes.',
example: false,
})
replayable!: boolean;
}
/** Body of `POST /webhooks/delivery-failures/redrive`. Every field narrows; an empty body takes eligible rows with the fewest attempts. */
export class RedriveWebhookDeliveriesDto {
@ApiPropertyOptional({
description: "Only rows of this session. Narrows within the calling key's allowedSessions, never past it.",
example: 'my-session',
})
@IsOptional()
@ToStrictString()
@IsString()
@MaxLength(128)
sessionId?: string;
@ApiPropertyOptional({ description: 'Only rows of this webhook.', example: '0a941dac-a965-45e7-b318-74ae8be134f0' })
@IsOptional()
@ToStrictString()
@IsString()
@MaxLength(128)
webhookId?: string;
@ApiPropertyOptional({
type: [String],
description: 'Only these failure rows (ids from `GET /webhooks/delivery-failures`).',
example: ['0a941dac-a965-45e7-b318-74ae8be134f0'],
maxItems: 500,
items: { type: 'string', maxLength: 128 },
})
@IsOptional()
@ToStrictArray()
@IsArray()
@ArrayMaxSize(500)
@IsString({ each: true })
@MaxLength(128, { each: true })
ids?: string[];
@ApiPropertyOptional({
description: 'Max rows replayed by this call (1-500, default 100).',
example: 100,
minimum: 1,
maximum: 500,
})
@IsOptional()
@IsInt()
@Min(1)
@Max(500)
limit?: number;
}
/** Outcome of `POST /webhooks/delivery-failures/redrive`. */
export class WebhookRedriveResultDto {
@ApiProperty({ description: 'Rows replayed by this call; equals delivered.', example: 2 })
redriven!: number;
@ApiProperty({ description: 'Delivered by a direct POST; their failure rows were removed.', example: 2 })
delivered!: number;
@ApiProperty({
description: 'Reserved for response compatibility; operator redrive uses direct POST and returns zero.',
example: 0,
})
enqueued!: number;
@ApiProperty({ description: 'Replays that failed again; their rows stay, with attempts raised by one.', example: 0 })
failed!: number;
@ApiProperty({
description: 'Rows not replayed: the webhook was removed, disabled or unsubscribed, or a plugin cancelled it.',
example: 0,
})
skipped!: number;
@ApiProperty({ description: 'Replayable rows still in scope after this call.', example: 0 })
remaining!: number;
}
/** Outcome of `POST /sessions/:sessionId/webhooks/:id/test`. */
export class WebhookTestResponseDto {
@ApiProperty({ description: 'True when the receiver answered 2xx.', example: true })
success!: boolean;
@ApiPropertyOptional({ description: 'The HTTP status the receiver answered, when it answered.', example: 200 })
statusCode?: number;
@ApiPropertyOptional({ description: 'The delivery error, when the attempt failed.', example: 'timeout' })
error?: string;
}