Module service_commons.webhook
commons/service_commons.webhook
Functions
sign
Signs a delivery: sha256= + hex HMAC-SHA256 of <timestamp>.<body>.
verify
function verify(Request req, string secret, int toleranceSeconds) returns WebhookEvent|errorVerifies a received delivery and returns its event. Use it in the receiving service.
Parameters
- req Request - The webhook request
- secret string - Shared secret
- toleranceSeconds int (default 300) - Largest accepted clock difference, which bounds replays
Return Type
- WebhookEvent|error - The event, or an error if the signature or timestamp is invalid
Classes
service_commons.webhook: Webhooks
Webhook subscriptions per participant, with a transactional outbox and signed, retried delivery.
Tables are <prefix>subscription and <prefix>outbox.
Constructor
Creates the registry and dispatcher.
init (Client db, DbType dbType, string ns, string prefix, DispatcherConfig config)- db Client - Database client; pass the service's own client so
enqueuejoins its transactions
- dbType DbType - Dialect
- ns string - Namespace
- prefix string - Table prefix, e.g.
chat_webhook_
- config DispatcherConfig {} - Delivery tuning
migrate
function migrate() returns error?Creates or upgrades the webhook tables.
Return Type
- error? - An error if a migration fails
register
function register(NewSubscription input) returns CreatedSubscription|errorRegisters a webhook for a participant.
Parameters
- input NewSubscription - The webhook
Return Type
- CreatedSubscription|error - The subscription with its secret, or an error
upsert
function upsert(WebhookConfig config) returns Subscription|errorRegisters a configured webhook, or updates the one with the same participant and URL.
Parameters
- config WebhookConfig - The webhook
Return Type
- Subscription|error - The subscription, or an error
list
function list(string? participantId) returns Subscription[]|errorLists webhooks.
Parameters
- participantId string? (default ()) - Only this participant's
Return Type
- Subscription[]|error - The subscriptions, or an error
get
function get(string id) returns Subscription?|errorGets a webhook.
Parameters
- id string - Subscription ID
Return Type
- Subscription?|error - The subscription,
()if unknown, or an error
remove
Removes a webhook and its pending deliveries.
Parameters
- id string - Subscription ID
enqueue
function enqueue(string event, string[] recipients, json data, string? correlationId) returns int|errorQueues an event for every webhook of the recipients that accepts it. Call it inside the transaction that
makes the change, so the event is queued exactly when the change commits; then call dispatch.
Parameters
- event string - Event name
- recipients string[] - Participants to notify
- data json - Event payload
- correlationId string? (default ()) - Correlation ID of the conversation or case
dispatch
function dispatch()Delivers due events in the background. Call it after the transaction that queued them commits.
deliverDue
Delivers due events now, oldest first.
deliveries
Lists a webhook's most recent deliveries.
startRetries
function startRetries() returns error?Schedules the retry job, which also prunes old delivered rows.
Return Type
- error? - An error if the job cannot be scheduled
Constants
service_commons.webhook: HEADER_EVENT
Header carrying the event name.
service_commons.webhook: HEADER_EVENT_ID
Header carrying the event ID.
service_commons.webhook: HEADER_SIGNATURE
Header carrying sha256=<hex HMAC of "<timestamp>.<body>">.
service_commons.webhook: HEADER_TIMESTAMP
Header carrying the send time in epoch seconds.
Enums
service_commons.webhook: DeliveryStatus
State of one delivery.
Members
Records
service_commons.webhook: CreatedSubscription
A newly registered webhook, with its secret. The secret is not returned again.
Fields
- Fields Included from *Subscription
- secret string - HMAC signing secret
service_commons.webhook: Delivery
One delivery of an event to a subscription.
Fields
- id string - Delivery ID
- eventId string - Event ID
- event string - Event name
- status DeliveryStatus - Delivery state
- attempts int - Attempts made
- createdAt string - RFC 3339 time the event was queued
- nextAttemptAt? string - RFC 3339 time of the next attempt, while pending
- deliveredAt? string - RFC 3339 time it was delivered
- lastError? string - Error of the last failed attempt
service_commons.webhook: DispatcherConfig
Delivery tuning.
Fields
- maxAttempts int(default 8) - Attempts before a delivery is marked FAILED
- initialBackoff decimal(default 1) - Delay before the first retry, in seconds; doubles each attempt
- maxBackoff decimal(default 300) - Longest delay between retries, in seconds
- timeout decimal(default 10) - Request timeout, in seconds
- retryInterval decimal(default 5) - How often pending deliveries are retried, in seconds
- keepDeliveredHours int(default 24) - Delivered rows are kept this long, in hours
service_commons.webhook: NewSubscription
A webhook to register through the API.
Fields
- participantId string - Participant whose events are delivered
- url string - Delivery endpoint
- events string[](default []) - Event names to deliver; empty delivers all
- secret? string - HMAC signing secret; generated when absent
service_commons.webhook: Subscription
A registered webhook.
Fields
- id string - Subscription ID
- participantId string - Participant whose events are delivered
- url string - Delivery endpoint
- events string[] - Event names delivered; empty means all
- createdAt string - RFC 3339 registration time
service_commons.webhook: WebhookConfig
A webhook registered from configuration, e.g. an agent's endpoint known at deploy time.
Fields
- participantId string - Participant whose events are delivered, e.g.
agent:maintenance-triage
- url string - Delivery endpoint
- secret string - HMAC signing secret shared with the receiver
- events string[](default []) - Event names to deliver; empty delivers all
service_commons.webhook: WebhookEvent
Body of every webhook delivery.
Fields
- eventId string - Unique per event; the receiver's idempotency key
- event string - Event name, e.g.
message.created
- ns string - Namespace the event belongs to
- recipientId string - Participant this delivery is for
- occurredAt string - RFC 3339 time the event happened
- correlationId? string - Correlation ID of the conversation or case
- data json - Event payload
Import
import commons/service_commons.webhook;Other versions
0.1.0