Klump Webhooks

generated: '2026-07-19'
method: searched
source: https://docs.useklump.com/docs/webhook-getting-started
spec_type: Webhooks
asyncapi_published: false
docs:
- https://docs.useklump.com/docs/webhook-getting-started
- https://docs.useklump.com/docs/setting-up-webhook
- https://docs.useklump.com/docs/resend-webhook
summary: Klump publishes no AsyncAPI document. It does document a single webhook
  family - Transaction - carrying three transaction lifecycle events, delivered as
  HTTP POST with a JSON body, HMAC-signed, and retried hourly for 72 hours.
transport:
  protocol: https
  method: POST
  content_type: application/json
  subscriber: A publicly reachable merchant URL registered in the merchant dashboard
    under Settings > API Keys & Webhook. Separate URLs can be registered for the TEST
    and LIVE application states, and each receives only the traffic generated by the
    matching key set.
  localhost: Tunnelling services such as ngrok are supported during development.
channels:
- name: transaction
  description: The only webhook family Klump currently supports.
events:
- name: klump.payment.transaction.initiated
  title: Transaction initiated
  description: Emitted when a transaction is initiated. Klump notes this event is
    informational only and requires no merchant action.
  action_required: false
- name: klump.payment.transaction.successful
  title: Transaction successful
  description: Emitted when a transaction completes successfully. Klump advises
    verifying the transaction via the verification API before releasing value.
  action_required: true
- name: klump.payment.transaction.abandoned
  title: Transaction abandoned
  description: Emitted when a transaction is abandoned. An abandoned transaction can
    later become successful if the shopper returns to pay via the periodic reminder
    email Klump sends, in which case the webhook event changes accordingly.
  action_required: true
headers:
- name: X-Klump-Signature
  description: HMAC signature of the request body, used to verify the call came from
    Klump and was not tampered with.
  example: ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb
- name: X-Klump-Webhook-Id
  description: Unique ID of the webhook call. The value is consistent across retries
    and is the intended deduplication key.
  example: 65843e9e-b12d-4120-8d1b-34abea95695e
- name: X-Klump-Webhook-Attempt
  description: Number of the delivery attempt, starting from 1.
  example: '1'
security:
  signature_header: X-Klump-Signature
  scheme: HMAC over the raw request body
  verification_samples_published:
  - javascript
  - php
  guidance:
  - Serve the endpoint over HTTPS with a certificate from a trusted authority.
  - Verify the X-Klump-Signature header on every call.
  - Keep the endpoint highly available.
  - Offload processing to a background job and acknowledge fast.
delivery:
  expected_response: 200 or 201
  retry_interval: hourly
  retry_window: 72 hours
  on_exhaustion: The request is abandoned after 72 hours without a 2xx acknowledgement.
  at_least_once: true
  idempotency_guidance: Klump explicitly instructs merchants to make webhook handling
    idempotent by checking X-Klump-Webhook-Id and refusing to process the same webhook
    twice.
  replay: A webhook can be resent for any past transaction using the Klump-generated
    transaction reference; the resend delivers the most recent state of the event.
    Documented at https://docs.useklump.com/docs/resend-webhook.