API Design

Webhook Event JSON Example

Webhook payload JSON example matching the format used by Stripe, GitHub, and Shopify webhooks. Includes event type, resource snapshot, and delivery metadata.

JSON

Open in Formatter

{
  "id": "evt_3PQkBN2eZvKYlo2M",
  "type": "order.created",
  "version": "2025-05-01",
  "createdAt": "2025-05-24T10:30:00Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "ord_7Kx9mP2nQ4",
      "status": "confirmed",
      "customer": {
        "id": "cust_9Lm3xR5",
        "email": "ravi@example.com"
      },
      "total": 1867.82,
      "currency": "INR",
      "createdAt": "2025-05-24T10:29:58Z"
    }
  },
  "delivery": {
    "attempt": 1,
    "maxAttempts": 5,
    "nextRetryAt": null
  }
}

Field Reference

idstringrequiredUnique event ID. Store processed IDs to deduplicate re-deliveries — webhooks are at-least-once.

typestringrequiredDot-separated event name like order.created or payment.failed. Use consistent naming across your API.

versionstringrequiredAPI version that generated this event. Lets consumers handle schema changes gracefully.

livemodebooleanrequiredfalse for test/sandbox events. Prevents test events from triggering real business actions.

data.objectobjectrequiredFull resource snapshot at the moment the event occurred. Avoids requiring a follow-up API call.

delivery.attemptintegeroptionalDelivery attempt count. Increments on retry after a failure or timeout.

Variants

GitHub PushShape used by GitHub webhook push events.

GitHub Push

Open in Formatter

{
  "ref": "refs/heads/main",
  "repository": {
    "id": 123456,
    "name": "my-repo",
    "full_name": "ravimehta/my-repo"
  },
  "pusher": {
    "name": "ravimehta",
    "email": "ravi@example.com"
  },
  "commits": [
    {
      "id": "abc123",
      "message": "Fix: handle null user",
      "timestamp": "2025-05-24T10:25:00Z"
    }
  ],
  "head_commit": {
    "id": "abc123",
    "message": "Fix: handle null user"
  }
}

Payment FailedEvent fired when a payment attempt fails.

Payment Failed

Open in Formatter

{
  "id": "evt_4QRlCO3fAwLZmp3N",
  "type": "payment.failed",
  "createdAt": "2025-05-24T10:30:00Z",
  "data": {
    "object": {
      "id": "pay_2MNjAL1dYuJXkn1L",
      "amount": 186782,
      "currency": "INR",
      "failureCode": "card_declined",
      "failureMessage": "Your card was declined."
    }
  }
}

Common Use Cases

→Real-time notifications when orders, payments, or users change state
→Triggering CI/CD pipelines on code push via GitHub or GitLab webhooks
→Syncing data between microservices without polling

webhookeventintegrationStripeGitHub

Validate or format this JSON

Paste the example above into JSONKit's tools to validate, minify, or explore the structure interactively.

Format →Validate →Minify →

Frequently Asked Questions

Make your handler idempotent: store the event id in a database table and skip processing if you have already seen that ID. Webhooks are delivered at-least-once, so receiving the same event twice is expected.

Always. The sender includes an HMAC-SHA256 signature of the payload in a request header. Verify it against your webhook secret before processing anything. This prevents spoofed requests from malicious actors.

Return 200 OK immediately, before doing any processing. If you return a 5xx or time out, the sender will retry the delivery. Acknowledge first, then process asynchronously in a job queue.

Related JSON Examples

API DesignREST API ResponseGeneric REST API response wrapper with data payload, status, and pagination meta.E-commerceE-commerce OrderFull e-commerce order JSON with line items, pricing, shipping, and payment status.API DesignError ResponseREST API error JSON with status code, machine-readable error code, and validation details.