Sign in
latestOpenAPI 3.1.02026-08-194237902.5 MB

563848e0ecc0

Webhooks

Drain the webhook delivery DLQ

Pulls failed webhook delivery events from the DLQ Pub/Sub subscription and re-enqueues them as Cloud Tasks for redelivery. Supports filtering by webhookId and tenantId. Use dryRun=true to preview without re-enqueuing. Requires the webhook:create permission and a tenant-id header. Note: the drain does a single bounded pull (maxMessages) and filters client-side, so on a DLQ dominated by other tenants a tenant-scoped drain may pull mostly non-matching messages and need to be re-run; increase maxMessages and/or repeat until the summary shows requeued==0 with an empty pull.

post/webhooks/dlq/drain

Headers

tenant-idstring required

Caller's tenant identifier. Required. The drain is scoped to this tenant: it overrides any tenantId supplied in the request body so callers cannot drain other tenants' failed webhooks.

Request body

maxMessagesinteger

Maximum number of messages to pull from the DLQ in this invocation. Integer between 1 and 1000; defaults to 100 when omitted.

webhookIdstring

Optional filter: only re-enqueue events for this webhook id. When omitted, events for all webhooks (within the tenant) are eligible.

tenantIdstring

Optional in the payload but always overridden by the tenant-id header for security; a caller-supplied value that differs from the header is ignored.

targetQueuestring

Optional Cloud Tasks queue to re-enqueue matching events to. Must be an allowed webhook delivery queue; defaults to the primary webhook-delivery queue when omitted.

dryRunboolean

When true, pull and inspect matching messages but do not re-enqueue them (messages are nacked back to the subscription). Defaults to false.

Example request

{
  "maxMessages": 100,
  "webhookId": "wh_9f8c2b1a4d6e",
  "targetQueue": "webhook-delivery"
}

Response

Drain summary: counts of messages pulled, re-enqueued, filtered out, and failed, plus per-message results. On a dry run, matching events are reported with status DRY_RUN and none are re-enqueued.

totalPulledinteger

Total messages pulled from the DLQ subscription in this drain.

requeuedinteger

Messages successfully re-enqueued to the target Cloud Tasks queue.

filteredinteger

Messages skipped because they did not match the webhookId/tenantId filter.

failedinteger

Messages that failed to re-enqueue; they remain in the DLQ and are retried on the next drain.

Example response

{
  "totalPulled": 12,
  "requeued": 8,
  "filtered": 3,
  "failed": 1,
  "results": [
    {
      "messageId": "7654321098765432",
      "webhookId": "wh_9f8c2b1a4d6e",
      "tenantId": "tenant_acme",
      "status": "REQUEUED",
      "detail": "to webhook-delivery"
    }
  ]
}