How It Works What It Catches Quickstart Pricing
Sign in Start 14-day trial

Quickstart: Add SendPromptly to One Payment Flow

Instrument one payment path with SendPromptly in an afternoon. Works with Stripe, Shopify, and any backend stack.

Start with the payment path that already causes support pain. SendPromptly adds two signals to your existing webhook handler. You do not need to proxy your payment provider, replace your webhook stack, or adopt a generic event platform.

Prerequisites

  • Active SendPromptly account — start a 14-day trial
  • An existing Stripe or Shopify webhook handler in your app
  • A dedicated repair endpoint you control (used only for reprocess callbacks)

Step 1 — Create a project

In app.sendpromptly.com, create a project. Generate an API key and store the plaintext sk_... value server-side only. The dashboard shows it once.

Configure your repair callback URL. This is the endpoint SendPromptly will POST to when you trigger a reprocess from the incident console.

Step 2 — Choose one event to instrument first

Start with one event type:

Stripe:

  • checkout.session.completed — for access unlock failures
  • invoice.paid — for credit grants or other paid-but-not-applied effects

Shopify:

  • orders/paid — for access or fulfillment effects after Shopify purchase

Do not try to instrument every event at once. One flow first, then expand.

Step 3 — Signal acceptance

After your webhook handler verifies the signature and durably accepts the work (for example, enqueues a job), signal SendPromptly:

1
2
3
4
5

POST https://api.sendpromptly.app/api/v1/receipt
Authorization: Bearer <project_api_key>
Idempotency-Key: <deterministic_unique_key>
Content-Type: application/json
Accept: application/json

Stripe example:

1
2
3
4
5
6
7
8

{
  "provider": "stripe",
  "stripe_event_id": "evt_123",
  "event_type": "checkout.session.completed",
  "effect_type": "access_unlock",
  "internal_reference": "user_456",
  "occurred_at": "2026-05-05T15:04:05Z"
}

Shopify example:

1
2
3
4
5
6
7
8
9

{
  "provider": "shopify",
  "provider_event_id": "wh_orders_paid_abc123",
  "event_type": "orders/paid",
  "effect_type": "access_unlock",
  "internal_reference": "order_98765",
  "shopify_shop_domain": "mystore.myshopify.com",
  "occurred_at": "2026-05-05T10:00:00Z"
}

Send this signal before your job queue runs the business effect — not after. A successful call returns 202 Accepted with event_id, timeout_at, and accepted: true.

Supported effect_type values: access_unlock, credit_grant, seat_update, subscription_state_apply, access_revocation, credit_deduction.

Step 4 — Signal the outcome

After your app attempts the business effect, report the outcome. For success:

1
2
3
4

{
  "stripe_event_id": "evt_123",
  "status": "success"
}

For failure:

1
2
3
4
5
6

{
  "stripe_event_id": "evt_123",
  "status": "failed",
  "error_code": "access_update_failed",
  "error_message": "User row lock timeout"
}

If no outcome arrives within the configured timeout (default 30 minutes), SendPromptly opens an incident automatically. You can override the timeout per event using "timeout_minutes" in the receipt payload — useful for time-sensitive revocation flows.

Send the outcome to:

1
2
3
4
5

POST https://api.sendpromptly.app/api/v1/result
Authorization: Bearer <project_api_key>
Idempotency-Key: <deterministic_unique_key>
Content-Type: application/json
Accept: application/json

Step 5 — Implement your repair endpoint

SendPromptly POSTs a signed callback to your repair endpoint when you trigger a reprocess from the incident console. Verify the signature before processing.

Signature headers:

1
2
3

X-SendPromptly-Timestamp: <unix_timestamp>
X-SendPromptly-Nonce: <nonce>
X-SendPromptly-Signature: v1=<hmac_sha256>

The signature is HMAC-SHA256 over timestamp + "." + nonce + "." + raw_body using your project’s signing secret. Reject callbacks with a timestamp older than 5 minutes. Your repair endpoint must be idempotent — it will receive the same replay_id on retries.

Callback payload:

1
2
3
4
5
6
7
8

{
  "replay_id": "rp_123",
  "stripe_event_id": "evt_123",
  "event_type": "checkout.session.completed",
  "effect_type": "access_unlock",
  "internal_reference": "user_456",
  "requested_at": "2026-05-05T15:40:00Z"
}

After running your repair logic, report the outcome with the replay_id included:

1
2
3
4
5

{
  "stripe_event_id": "evt_123",
  "status": "success",
  "replay_id": "rp_123"
}

Step 6 — Test the integration

  1. Send a test event via your payment provider’s test dashboard
  2. Confirm your app sends the acceptance signal — check the SendPromptly console
  3. Force a failure outcome to trigger an incident
  4. Confirm the email alert arrives
  5. Click Reprocess from the incident console
  6. Confirm your repair endpoint receives the signed callback
  7. Send a success outcome
  8. Confirm the incident resolves

Use the Integration Test screen in the console for pre-filled curl commands scoped to your project.

Language examples

Node.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

await fetch("https://api.sendpromptly.app/api/v1/receipt", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SENDPROMPTLY_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify(payload)
})

PHP (Laravel):

1
2
3
4
5
6

Http::withToken(config('services.sendpromptly.key'))
    ->withHeaders([
        'Idempotency-Key' => (string) Str::uuid(),
        'Accept' => 'application/json',
    ])
    ->post('https://api.sendpromptly.app/api/v1/receipt', $payload);

Python:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

requests.post(
    "https://api.sendpromptly.app/api/v1/receipt",
    headers={
        "Authorization": f"Bearer {os.environ['SENDPROMPTLY_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Accept": "application/json",
    },
    json=payload,
    timeout=5
)

What not to instrument first

  • Every event type at once — instrument one, validate it, then expand
  • Every adjacent billing edge case — the highest-risk paths are invoice.paid, checkout.session.completed, and orders/paid
  • Generic webhook logging — that is not what SendPromptly does