Events and webhooks

{
  "url": "https://hooks.example.com/payerworks/events"
}

{
  "url": "https://hooks.example.com/payerworks/events",
  "secret": "whsec_bTqF5EiMSt1kZ4Sh577Ya/UQMCWse+eDI5CyF9JdOsk=",
  "secret_last_four": "Osk=",
  "created_at": "2026-10-19T15:00:00.000Z",
  "rotated": false,
  "previous_secret_expires_at": null
}

{
  "deleted": true
}

{
  "queued": true,
  "event_id": "evt_7cb356efb22e856293c87091"
}

{
  "data": [
    {
      "id": "evt_4fbc127e84a0331dfb743e10",
      "type": "sandbox.remittance.received",
      "created": 1792422000,
      "mode": "test",
      "data": {
        "check_number": "PWSANDBOX-000000003-1",
        "payment_date": "20261019",
        "total": 1392,
        "claims": [
          {
            "reference": "PW-SBX-PAID",
            "payer_claim_number": "PWS2292711347",
            "status_code": "1",
            "status": "processed as primary",
            "paid": 1392
          }
        ]
      },
      "delivery": {
        "state": "delivered",
        "attempts": 1,
        "last_status": 200,
        "last_attempt_at": "2026-10-19T15:00:00.000Z",
        "last_error": null,
        "delivered_at": "2026-10-19T15:00:00.000Z"
      }
    },
    {
      "id": "evt_e38518c4523f2dcd24e34de2",
      "type": "sandbox.claim.acknowledged",
      "created": 1792422000,
      "mode": "test",
      "data": {
        "reference": "PW-SBX-PAID",
        "payer_claim_number": "PWS2292711347",
        "verdict": "A",
        "fixes": [
          "The claim was accepted into the payer's adjudication system: accepted for processing (STC A2:20). Nothing to fix."
        ]
      },
      "delivery": {
        "state": "delivered",
        "attempts": 1,
        "last_status": 200,
        "last_attempt_at": "2026-10-19T15:00:00.000Z",
        "last_error": null,
        "delivered_at": "2026-10-19T15:00:00.000Z"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "cur_45233137393234313634363138393523303031236576745f376362333536656662323265383536323933633837303931"
}

{
  "id": "evt_4fbc127e84a0331dfb743e10",
  "type": "sandbox.remittance.received",
  "created": 1792422000,
  "mode": "test",
  "data": {
    "check_number": "PWSANDBOX-000000003-1",
    "payment_date": "20261019",
    "total": 1392,
    "claims": [
      {
        "reference": "PW-SBX-PAID",
        "payer_claim_number": "PWS2292711347",
        "status_code": "1",
        "status": "processed as primary",
        "paid": 1392
      }
    ]
  },
  "delivery": {
    "state": "delivered",
    "attempts": 1,
    "last_status": 200,
    "last_attempt_at": "2026-10-19T15:00:00.000Z",
    "last_error": null,
    "delivered_at": "2026-10-19T15:00:00.000Z"
  }
}

{
  "destination_id": "wd_4e1687f5d8638cbd"
}

{
  "queued": true,
  "event_id": "evt_4fbc127e84a0331dfb743e10",
  "destination_id": "wd_4e1687f5d8638cbd"
}

{
  "event_id": "evt_298da382d80136d9249cf920",
  "data": [
    {
      "event_id": "evt_298da382d80136d9249cf920",
      "destination_id": "wd_4e1687f5d8638cbd",
      "number": 1,
      "type": "automatic",
      "delivered": false,
      "status": 503,
      "error": "The endpoint answered 503; only a 2xx counts as delivered.",
      "at": "2026-10-20T19:12:00.093Z"
    }
  ]
}

{
  "data": [
    {
      "id": "wd_4e1687f5d8638cbd",
      "name": "Primary",
      "url": "https://hooks.example.com/payerworks/primary",
      "event_types": [
        "sandbox.claim.acknowledged",
        "sandbox.remittance.received"
      ],
      "enabled": true,
      "concurrency": 2,
      "secret_last_four": "J+c=",
      "previous_secret_expires_at": null,
      "disabled_at": null,
      "disabled_reason": null,
      "failing_since": null,
      "notices": [],
      "created_at": "2026-10-20T19:12:00.036Z",
      "updated_at": "2026-10-20T19:12:00.036Z"
    }
  ]
}

{
  "name": "Primary",
  "url": "https://hooks.example.com/payerworks/primary",
  "event_types": [
    "sandbox.claim.acknowledged",
    "sandbox.remittance.received"
  ],
  "concurrency": 2
}

{
  "id": "wd_4e1687f5d8638cbd",
  "name": "Primary",
  "url": "https://hooks.example.com/payerworks/primary",
  "event_types": [
    "sandbox.claim.acknowledged",
    "sandbox.remittance.received"
  ],
  "enabled": true,
  "concurrency": 2,
  "secret_last_four": "J+c=",
  "previous_secret_expires_at": null,
  "disabled_at": null,
  "disabled_reason": null,
  "failing_since": null,
  "notices": [],
  "created_at": "2026-10-20T19:12:00.036Z",
  "updated_at": "2026-10-20T19:12:00.036Z",
  "secret": "whsec_Y9WgA88flTmkMq89BiZzDzjILhNojHvXhMpB0Td1J+c="
}

{
  "id": "wd_4e1687f5d8638cbd",
  "name": "Primary",
  "url": "https://hooks.example.com/payerworks/primary",
  "event_types": [
    "sandbox.claim.acknowledged",
    "sandbox.remittance.received"
  ],
  "enabled": true,
  "concurrency": 2,
  "secret_last_four": "J+c=",
  "previous_secret_expires_at": null,
  "disabled_at": null,
  "disabled_reason": null,
  "failing_since": null,
  "notices": [],
  "created_at": "2026-10-20T19:12:00.036Z",
  "updated_at": "2026-10-20T19:12:00.036Z"
}

{
  "rotate": true,
  "overlap_hours": 48
}

{
  "id": "wd_4e1687f5d8638cbd",
  "name": "Primary",
  "url": "https://hooks.example.com/payerworks/primary",
  "event_types": [
    "sandbox.claim.acknowledged",
    "sandbox.remittance.received"
  ],
  "enabled": true,
  "concurrency": 2,
  "secret_last_four": "nHY=",
  "previous_secret_expires_at": "2026-10-22T19:12:00.046Z",
  "disabled_at": null,
  "disabled_reason": null,
  "failing_since": null,
  "notices": [],
  "created_at": "2026-10-20T19:12:00.036Z",
  "updated_at": "2026-10-20T19:12:00.046Z",
  "secret": "whsec_+3n+g2Y/+EkwVwm/9GiroC62uAVWtcbDgxSrcoK2nHY="
}

{
  "id": "wd_4e1687f5d8638cbd",
  "deleted": true
}

{
  "queued": true,
  "event_id": "evt_9b13ad1f89c0ff82ddbb2bf1",
  "destination_id": "wd_4e1687f5d8638cbd"
}

{
  "data": [
    {
      "event_id": "evt_298da382d80136d9249cf920",
      "event_type": "sandbox.remittance.received",
      "destination_id": "wd_4e1687f5d8638cbd",
      "created_at": "2026-10-20T19:12:00.057Z",
      "state": "scheduled",
      "attempts": 1,
      "next_attempt_at": "2026-10-20T19:17:00.093Z",
      "last_attempt_at": "2026-10-20T19:12:00.093Z",
      "last_status": 503,
      "last_error": "The endpoint answered 503; only a 2xx counts as delivered.",
      "delivered_at": null
    },
    {
      "event_id": "evt_de844b60d20dade1dfdfdf52",
      "event_type": "sandbox.claim.acknowledged",
      "destination_id": "wd_4e1687f5d8638cbd",
      "created_at": "2026-10-20T19:12:00.057Z",
      "state": "scheduled",
      "attempts": 1,
      "next_attempt_at": "2026-10-20T19:17:00.093Z",
      "last_attempt_at": "2026-10-20T19:12:00.093Z",
      "last_status": 503,
      "last_error": "The endpoint answered 503; only a 2xx counts as delivered.",
      "delivered_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

// Payerworks example: events, signed, listed and sent again. Docs: https://payerworks.com/docs/events
//
// Run it with Node 18 or later, with the JavaScript client (https://payerworks.com/sdk/payerworks.mjs)
// and sample-data.mjs beside this file:
//   PAYERWORKS_API_KEY=pw_test_... PAYERWORKS_BASE_URL=<the base URL shown with your key> node events.mjs
// A test key and invented data only. Payerworks sends nothing to a payer: every file it writes is yours.
import { pathToFileURL } from 'node:url';
import { Payerworks, PayerworksError, verifyStandardWebhook } from './payerworks.mjs';
import { SENDER_ID, claimEndingIn, refusalOf } from './sample-data.mjs';

/**
 * On YOUR server, for each delivery: check the signature over the raw body, before you parse it.
 * `secret` is the whsec_ secret PUT /v1/account/webhook answered once; `headers` the request's headers.
 * A delivery may arrive more than once: skip a webhook-id you have handled.
 * @param {string} secret @param {Record<string, string>} headers @param {string} rawBody
 */
export function readDelivery(secret, headers, rawBody, seen = new Set()) {
  if (!verifyStandardWebhook(secret, headers, rawBody)) return { ok: false, reason: 'signature' };
  const id = headers['webhook-id'];
  if (seen.has(id)) return { ok: true, duplicate: true };
  seen.add(id);
  return { ok: true, event: JSON.parse(rawBody) };
}

/** @param {Payerworks} pw */
export async function run(pw) {
  // 1. Your webhook: an https address of yours. The signing secret is shown once: store it.
  const hook = await pw.putAccountWebhook({ url: 'https://hooks.example.com/payerworks' });

  // 2. A sandbox run makes events: the 999, each claim's 277CA, and each check's 835.
  const sandbox = await pw.postSandboxClaims({ sender_id: SENDER_ID, claims: [claimEndingIn('')] });

  // 3. Every event is kept for 30 days: list them, read one, and send one again.
  const listed = await pw.getEvents({ query: { limit: 10 } });
  const one = await pw.getEventsById(listed.data[0].id);
  const again = await pw.postEventsByIdRedeliver(one.id);

  // 4. The failure path: an id this key never had.
  const refused = await refusalOf(() => pw.getEventsById(`evt_${'0'.repeat(24)}`), { PayerworksError });

  return {
    secret_starts: hook.secret.slice(0, 6),
    made: sandbox.events.map((e) => e.type),
    listed: listed.data.length,
    redelivered: Boolean(again),
    refused,
  };
}

// Run as a script: node <this file>, with PAYERWORKS_API_KEY and PAYERWORKS_BASE_URL set.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run(new Payerworks()), null, 2));
}

{
  "secret_starts": "whsec_",
  "made": [
    "sandbox.file.acknowledged",
    "sandbox.claim.acknowledged",
    "sandbox.remittance.received"
  ],
  "listed": 3,
  "redelivered": true,
  "refused": {
    "status": 404,
    "code": "event_not_found",
    "request_id": "req_6"
  }
}