Webhooks - Justpaid Docs

Overview

Webhooks are a way for your application to receive real-time notifications when events occur in your account. When an event occurs, we send an HTTP POST request to the webhook’s configured URL. You can use webhooks to trigger custom code, workflows, or integrations in your application.

Creating Webhooks

You can create and manage webhooks directly from the JustPaid dashboard:

Navigate to Settings → Developer → Webhooks
Click Create Webhook URL
Enter your webhook endpoint URL
Select the event types you want to subscribe to
Click Save

Each webhook includes a signing secret that you can use to verify the authenticity of incoming requests.

Two Different Naming Schemes

JustPaid uses two distinct sets of event-type strings, and mixing them up is the single most common integration bug.

Subscription identifiers are UPPER_SNAKE_CASE (e.g. INVOICE_STATUS_CHANGE). These are what you select in the dashboard and what appear in the API when configuring which events an endpoint receives.
Delivered event types are lowercase.dotted (e.g. invoice.status_changed). This is the value that actually arrives in the type field of the JSON body we POST to your endpoint.

Match your receiver on the lowercase.dotted values. If you compare the incoming type against INVOICE_STATUS_CHANGE, no event will ever match and your receiver will silently ignore every delivery.

Common integration mistake

A receiver written like this will drop every JustPaid event:

// WRONG — the wire value is never UPPER_SNAKE
if (body.type === "INVOICE_STATUS_CHANGE") { /* never runs */ }
return { status: 200, ignored: true, eventType: body.type };

Compare against the delivered value instead:

// CORRECT — matches what we actually send
if (body.type === "invoice.status_changed") { /* handle it */ }

Returning 200 while ignoring the event means retries will not fire and the delivery is recorded as successful on our side, so this failure mode is silent. Log unmatched type values during integration to catch it.

Event Types

The table below is exhaustive. Every value listed is a real, deliverable event type; there are no others.

Subscription identifier (dashboard)	Delivered `type` (wire value)	Fires when
`INVOICE_CREATED`	`invoice.created`	A new invoice is created — including DRAFT invoices
`INVOICE_UPDATED`	`invoice.updated`	An invoice is updated and a tracked field changed (see note below)
`INVOICE_STATUS_CHANGE`	`invoice.status_changed`	An invoice’s status changes
`INVOICE_PAYMENT_STATUS_CHANGE`	`invoice_payment.status_changed`	A payment’s status changes on an invoice
`CUSTOMER_CREATED`	`customer.created`	A new customer is created
`CUSTOMER_CONTRACT_CREATED`	`contract.created`	A new contract is created for a customer
`PRODUCT_CREATED`	`product.created`	A new product is created
`PRODUCT_UPDATED`	`product.updated`	An existing product is updated
`CREDIT_MEMO_CREATED`	`credit_memo.created`	A new credit memo is created
`CREDIT_MEMO_UPDATED`	`credit_memo.updated`	An existing credit memo is updated
`CREDIT_MEMO_STATUS_CHANGE`	`credit_memo.status_changed`	A credit memo’s status changes

Note that CUSTOMER_CONTRACT_CREATED maps to contract.created — the wire value drops the customer_ prefix. It is the one pair where the two names are not a mechanical transformation of each other.

Behavior worth knowing

invoice.created fires for DRAFT invoices. Creation is creation regardless of status — the event is emitted as soon as the invoice row is committed, so the invoice_status in your first event for an invoice is frequently draft. If you only care about issued invoices, filter on invoice_status or subscribe to invoice.status_changed instead. invoice.updated requires a tracked-field change. An update only emits an event when one of these fields actually changed value:

amount
due_date
invoice_date
description
notes

Editing anything else on an invoice produces no invoice.updated event. Do not rely on this event as a general “something about this invoice changed” signal. Status-change events carry the old value. invoice.status_changed, invoice_payment.status_changed, and credit_memo.status_changed include a data.previous_attributes object holding the prior status (invoice_status, payment_status, and memo_status respectively). It is only present when the status genuinely changed.

Payload Envelope

Every delivery uses the same envelope, regardless of event type:

Field	Type	Description
`id`	string	Unique event identifier, always prefixed `evt_` followed by 32 hex characters. Use it for idempotency.
`object`	string	Always the literal `"event"`.
`api_version`	string	Always `"v1"`.
`created`	string	ISO 8601 timestamp with timezone offset, e.g. `2026-01-27T10:30:00.123456+00:00`. A string, not a Unix integer.
`type`	string	The `lowercase.dotted` event type. This is the key that carries the event type.
`data.object`	object	The entity, using the same schema as the corresponding REST API resource.
`data.previous_attributes`	object	Only present on change events. Maps changed field names to their previous values. Absent entirely on `*.created` events.

The request body is serialized with sorted keys and no whitespace before signing, so field order on the wire is alphabetical.

Example: `invoice.status_changed`

{
  "api_version": "v1",
  "created": "2026-01-27T10:30:00.123456+00:00",
  "data": {
    "object": {
      "uuid": "d0b1c4c0-4b1e-4b3e-8b4b-1f1d8b1d8b1d",
      "invoice_number": "INV-2026-001",
      "invoice_status": "sent",
      "amount": 1500.0,
      "currency": "USD",
      "invoice_date": "2026-01-27",
      "due_date": "2026-02-26",
      "description": "January services",
      "notes": null,
      "payment_link": "https://pay.justpaid.io/...",
      "created_at": "2026-01-27T10:00:00Z",
      "updated_at": "2026-01-27T10:30:00Z",
      "customer": {
        "uuid": "9c1e4b3e-8b4b-1f1d-8b1d-8b1dd0b1c4c0",
        "name": "Acme Corporation",
        "email": "billing@acme.com"
      },
      "line_items": []
    },
    "previous_attributes": {
      "invoice_status": "Draft"
    }
  },
  "id": "evt_4f3a9c1e8b7d6a5f4e3d2c1b0a9f8e7d",
  "object": "event",
  "type": "invoice.status_changed"
}

Example: `invoice.created`

A *.created event has no previous_attributes key at all:

{
  "api_version": "v1",
  "created": "2026-01-27T10:00:00.000000+00:00",
  "data": {
    "object": {
      "uuid": "d0b1c4c0-4b1e-4b3e-8b4b-1f1d8b1d8b1d",
      "invoice_number": "INV-2026-001",
      "invoice_status": "draft",
      "amount": 1500.0,
      "currency": "USD",
      "customer": {
        "uuid": "9c1e4b3e-8b4b-1f1d-8b1d-8b1dd0b1c4c0",
        "name": "Acme Corporation",
        "email": "billing@acme.com"
      },
      "line_items": []
    }
  },
  "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "object": "event",
  "type": "invoice.created"
}

Webhook Headers

Header	Description
`Content-Type`	Always `application/json`
`X-JustPaid-Timestamp`	Unix timestamp (seconds, as a string) when the request was signed
`X-JustPaid-Signature`	HMAC-SHA256 signature in the format `v1={sha256_hex}`

The two signature headers are sent only when a signing secret is configured on the webhook endpoint. Endpoints without a secret receive only Content-Type.

Signature Verification

The signed input is the timestamp and the raw body joined by a literal period: {timestamp}.{body}. The key is your endpoint’s signing secret. Verify against the raw request body bytes exactly as received — we sign the compact, key-sorted JSON we transmit, so re-serializing a parsed object will produce a different string and the signature will not match.

import hmac
import hashlib

def verify_justpaid_webhook(payload_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    expected_sig = hmac.new(
        secret.encode('utf-8'),
        f"{timestamp}.{payload_body.decode('utf-8')}".encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    provided_sig = signature.replace("v1=", "")
    return hmac.compare_digest(expected_sig, provided_sig)

Delivery and Retries

Webhooks are delivered asynchronously on a background queue, after the originating database transaction commits.
Each subscribed endpoint is dispatched independently. A failure on one endpoint does not prevent delivery to the others, and a retry never re-sends to an endpoint that already accepted the event.
Up to 3 retries, at a fixed 60-second delay between attempts (not exponential backoff).
Connection timeout is 5 seconds; response timeout is 30 seconds. Return a 2xx within 30 seconds or the attempt is treated as failed.
Every attempt is logged, including the request body, request headers, response status code, and response body. These are visible per endpoint in the dashboard and are the fastest way to diagnose an integration.
The event id is stable across retries, so it is safe to use for idempotency/deduplication.

Which failures are retried

Response	Retried?
2xx	No — delivered
`408 Request Timeout`, `429 Too Many Requests`	Yes
Any other 4xx	No — a re-POST cannot fix a request the endpoint rejected
5xx, connection errors, timeouts	Yes

Endpoints are never auto-disabled. No matter how many deliveries fail or for how long, we keep attempting future events to a configured endpoint. If an endpoint is dead, remove or update it in the dashboard — it will not deactivate itself, and repeated failures will not stop us from trying.

Best Practices

Match on the delivered type — the lowercase.dotted value, never the UPPER_SNAKE subscription identifier
Respond quickly — return a 2xx status code within 30 seconds
Process asynchronously — acknowledge immediately, then queue the event for background processing
Verify signatures — validate X-JustPaid-Signature against the raw body bytes
Handle duplicates — use the event id for idempotency; it is stable across retries
Log unmatched event types — the surest way to catch a naming mismatch before it becomes silent data loss
Handle out-of-order delivery — events are delivered in order when possible, but independent dispatch and retries mean ordering is not guaranteed

​Overview

​Creating Webhooks

​Two Different Naming Schemes

​Common integration mistake

​Event Types

​Behavior worth knowing

​Payload Envelope

​Example: invoice.status_changed

​Example: invoice.created

​Webhook Headers

​Signature Verification

​Delivery and Retries

​Which failures are retried

​Best Practices

Overview

Creating Webhooks

Two Different Naming Schemes

Common integration mistake

Event Types

Behavior worth knowing

Payload Envelope

Example: `invoice.status_changed`

Example: `invoice.created`

Webhook Headers

Signature Verification

Delivery and Retries

Which failures are retried

Best Practices