ascend-webhooks

---
name: ascend-webhooks
description: >
license: MIT
---

# Ascend Webhooks

Ascend (insurance payments / premium financing) sends webhooks so your app is
notified when an event happens — for example when an invoice is paid. Ascend
POSTs a JSON payload over HTTPS and signs it with an HMAC-SHA256 signature you
must verify before trusting the event.

## When to Use This Skill

- How do I receive Ascend webhooks?
- How do I verify Ascend webhook signatures?
- How do I parse the `X-Ascend-Signature` header?
- How do I handle `invoice.paid` (or payout / refund) events?
- Why is my Ascend webhook signature verification failing?

## How Ascend Signs Webhooks

Ascend uses a **custom Stripe-style HMAC-SHA256 scheme** (not Svix, not
Standard Webhooks). Two headers are sent:

| Header | Example | Purpose |
|--------|---------|---------|
| `X-Ascend-Signature` | `t=1696200697,v1=5257a869e7...` | Timestamp + HMAC signature |
| `X-Ascend-Request-Timestamp` | `1696200697` | Same Unix timestamp (redundant) |

The signature is verified by:

1. Parse `X-Ascend-Signature` into `t` (timestamp) and `v1` (hex HMAC).
2. Build the signed string as `` `${t}:${rawBody}` `` — the timestamp, a **colon**, then the **raw request body**.
3. Compute `HMAC-SHA256(signed_string, webhook_secret)` and hex-encode it.
4. Constant-time compare against `v1`.

> **Use the raw request body.** Re-serializing the parsed JSON (key reordering,
> whitespace) changes the bytes and breaks the signature. There is no official
> Ascend SDK, so every framework below verifies manually.

## Verification (core)

```javascript
const crypto = require('crypto');

// Verify Ascend's "t=<timestamp>,v1=<hex>" signature over "<timestamp>:<rawBody>".
function verifyAscendSignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('=').map((s) => s.trim()))
  );
  const { t: timestamp, v1: signature } = parts;
  if (!timestamp || !signature) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}:${rawBody}`) // colon separator + RAW body
    .digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false; // length mismatch = invalid
  }
}
```

> **For complete handlers with tests**, see [examples/express/](examples/express/), [examples/nextjs/](examples/nextjs/), [examples/fastapi/](examples/fastapi/).

## Event Payload Structure

Every event has the same top-level shape. Unlike Stripe, `data` **is** the
resource object directly (there is no `data.object` wrapper):

```json
{
  "id": "ajskljfaklsjd0912132",
  "type": "invoice.paid",
  "data": {
    "id": "684c8c8e-75eb-4134-925a-cb3a30f23633",
    "status": "paid",
    "payee": "John Doe Trucking",
    "payer_name": "John Doe",
    "total_amount_cents": 600000,
    "invoice_number": "II2DH1HGHJ",
    "paid_at": "2023-10-01T23:51:37.507Z"
  }
}
```

## Common Event Types

| Event | Triggered When |
|-------|----------------|
| `invoice.created` | An invoice is created |
| `invoice.processing_payment` | An invoice payment is being processed |
| `invoice.paid` | An invoice is paid |
| `invoice.voided` | An invoice is voided |
| `invoice.marked_overdue` | An invoice is marked overdue |
| `payout.paying` | A payout is being paid out |
| `payout.paid` | A payout has been paid |
| `payout.on_hold` | A payout is placed on hold |
| `payout.canceled` | A payout is canceled |
| `payout.failed` | A payout failed |
| `refund.paid` | A refund has been paid |
| `refund.cancelled` | A refund was cancelled |

Always branch on the `type` field and handle unknown types gracefully. See
[references/overview.md](references/overview.md) for the full list and payloads.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `ASCEND_WEBHOOK_SECRET` | The webhook signing secret provided by Ascend |

## Setup

Ascend webhook registration is **manual** — there is no self-serve dashboard.
Email `developers@useascend.com` with your organization, environment
(sandbox/production), the events you want, and your HTTPS endpoint URL. Ascend
returns a webhook signing secret. See [references/setup.md](references/setup.md).

## Local Development

For local webhook testing, run the Hookdeck CLI via `npx` — no install required:

```bash
npx hookdeck-cli listen 3000 ascend --path /webhooks/ascend
```

No account required — the CLI creates a guest account on first run and provides
a local tunnel + web UI for inspecting requests.

## Reference Materials

- [overview.md](references/overview.md) — What Ascend webhooks are, event types, payload structure
- [setup.md](references/setup.md) — Registering your endpoint and getting the signing secret
- [verification.md](references/verification.md) — Signature verification details and gotchas
- [examples/express/](examples/express/) — Express (Node.js) example with tests
- [examples/nextjs/](examples/nextjs/) — Next.js App Router example with tests
- [examples/fastapi/](examples/fastapi/) — FastAPI (Python) example with tests

## Recommended: webhook-handler-patterns

Install [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns)
alongside this skill for cross-cutting concerns:

- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md)
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)

## Related Skills

- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe's HMAC-SHA256 `t=,v1=` scheme (Ascend mirrors this style)
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - HMAC-SHA256 signature verification
- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - HMAC-SHA256 with Base64 encoding
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure