Webhooks

Receive signed HTTPS notifications for push and request events

🚀 Beta — Webhooks are currently in beta. We’re still improving the experience and welcome feedback.

This article applies to: Hosted (Pro)

Webhooks send an HTTPS POST to your endpoint when selected push or request events happen in a workspace. The JSON body is metadata only — it never includes secret content such as push payloads, passphrases, or request responses.

Deliveries are signed with the Standard Webhooks specification (whsec_... secrets and webhook-* headers), so you can verify them with common SDKs.

Availability

Platform Status
pwpush.com Pro ✅ Available (beta)
pwpush.com Premium Not available
pwpush.com Free Not available
Self-Hosted Pro Not available
Open Source Edition Not available

Webhooks are configured per workspace. Only workspace admins can create, edit, enable, disable, and delete endpoints. You can enable up to 5 webhook endpoints per workspace.

Quick start

  1. Sign in on us.pwpush.com or eu.pwpush.com with an active Pro subscription.
  2. Open Workspace → Policy → Webhooks.
  3. Choose Add Webhook.
  4. Fill in:
    • Name — a label for the endpoint (for example, Ops Slack)
    • Webhook URL — a public https:// endpoint
    • Signing Secret — generate a Standard Webhooks secret (whsec_...) in the UI
    • Events — which push and request events should trigger delivery
  5. Leave Enabled checked and save.

Tip: start with one event (for example, Response received), confirm a delivery in Recent Deliveries, then subscribe to more events.

What your endpoint receives

Each delivery is an HTTPS POST with a JSON body and these headers:

Header Description
Content-Type application/json
User-Agent Password-Pusher-Webhook/1.0
webhook-id Unique message ID (msg_...) — use for idempotency
webhook-timestamp Unix timestamp used for signing
webhook-signature Standard Webhooks signature (v1,...)

Your URL must:

  • Use HTTPS
  • Resolve to a public host (localhost, private, and other blocked addresses are rejected)
  • Return an HTTP 2xx status for a successful delivery

Example payload

{
  "type": "push.created",
  "occurred_at": "2026-07-19T15:30:00.000000Z",
  "data": {
    "workspace": {
      "id": "acct_oxQdpMWVm",
      "name": "Your Corporation"
    },
    "metadata": {
      "has_files": true
    },
    "push": {
      "url_token": "fjah-38fj2lanvbfke",
      "created_at": "2026-07-19T15:30:00.000000Z",
      "expires_at": "2026-07-20T15:30:00.000000Z"
    }
  }
}

Request events use a request object instead of push. For request.response_received, the body also includes responded_at and metadata.include_requestor. See Payload details.

Events

Select one or more events when you create or edit a webhook. Only subscribed events create deliveries.

Push events

UI label Payload type Triggered when
Push creation push.created A push is created
Push first view push.first_viewed The push page is viewed for the first time
Push expiration push.expired The push expires (manual expire, timed expire, or last-view expire)

Request events

UI label Payload type Triggered when
Request creation request.created A request is created
Request first view request.first_viewed The request page is viewed for the first time
Response received request.response_received A response is submitted to the request
Request close request.closed The request is closed

Payload details

Every delivery body is JSON with this shape:

Field Description
type Event name from the tables above
occurred_at UTC time the event occurred (ISO8601 with microseconds)
data.workspace.id Workspace ID (acct_...)
data.workspace.name Workspace name
data.metadata.has_files Whether the push or request has file attachments
data.metadata.include_requestor Request events only
data.push / data.request Resource metadata (url_token, timestamps, and for requests: state)
data.request.responded_at Only for request.response_received

Sensitive fields such as push payloads, passphrases, and request response content are never included. If your workflow needs secret content, retrieve it through the Password Pusher UI or API v2.

Request example

{
  "type": "request.response_received",
  "occurred_at": "2026-07-19T15:30:00.000000Z",
  "data": {
    "workspace": {
      "id": "acct_oxQdpMWVm",
      "name": "Your Corporation"
    },
    "metadata": {
      "has_files": false,
      "include_requestor": true
    },
    "request": {
      "url_token": "fjah-38fj2lanvbfke",
      "state": "ready",
      "created_at": "2026-07-18T10:00:00.000000Z",
      "expires_at": "2026-07-19T12:00:00.000000Z",
      "responded_at": "2026-07-19T15:30:00.000000Z"
    }
  }
}

Verifying signatures

Password Pusher signs each delivery with your webhook’s signing secret using Standard Webhooks.

  1. Read webhook-id, webhook-timestamp, and webhook-signature from the request headers.
  2. Verify the signature against the raw request body with your whsec_... secret.
  3. Reject requests with invalid signatures or timestamps outside your accepted tolerance.

Secrets use the Standard Webhooks format: a whsec_ prefix followed by a Base64-encoded key. Store the secret securely — it is encrypted at rest in Password Pusher and shown as configured (not re-displayed in full) after save.

Most Standard Webhooks SDKs can verify these deliveries without custom crypto. Official packages for Python, JavaScript/TypeScript, Ruby, Go, Java, and other languages are listed under Reference implementations.

Idempotency

Every delivery has a unique message ID (msg_...). That value is:

  • Sent as the webhook-id header
  • Included in the Standard Webhooks signature
  • Shown in Recent Deliveries and related audit-log entries

Automatic retries and manual Retry reuse the same message ID. Your endpoint may therefore receive the same event more than once with an identical webhook-id.

Treat webhook-id as an idempotency key: record IDs you have already processed and ignore duplicates so side effects run only once.

Delivery and retries

  • Deliveries are sent asynchronously after the related event is recorded.
  • Success means your endpoint returned HTTP 2xx.
  • Transient failures (timeouts, connection errors, HTTP 5xx, or 429) are retried automatically — up to 3 attempts with increasing delay — using the same webhook-id.
  • Permanent failures (other non-2xx responses, blocked hosts, and similar) are marked failed and logged.
  • Successful and failed deliveries appear in the push or request audit log, and on the webhook’s Recent Deliveries list.
  • Failed deliveries can be retried from the UI while the webhook remains enabled. Retries keep the original message ID.

Security notes

  • Use HTTPS endpoints only; HTTP URLs are rejected.
  • Private and loopback destinations are blocked to reduce SSRF risk.
  • Always verify the Standard Webhooks signature before trusting a payload.
  • Treat webhook payloads as metadata only.

See also