Webhook payload design in Rest API

Introduction

A webhook payload is the information sent from one app to another when something happens. Designing it well helps apps understand and use the data easily.

When you want to notify another app instantly about an event, like a new user signup.

When you need to send data updates from your app to a partner app automatically.

When you want to trigger actions in another system based on your app's events.

When building integrations that rely on real-time data exchange between services.

Syntax

Rest API

{
  "event": "string",
  "timestamp": "ISO 8601 string",
  "data": {
    "key1": "value1",
    "key2": "value2",
    "...": "..."
  }
}

The payload is usually a JSON object.

Include an event name, a timestamp, and a data section with details.

Examples

This payload tells the receiver a new user was created with their ID and email.

Rest API

{
  "event": "user.created",
  "timestamp": "2024-06-01T12:00:00Z",
  "data": {
    "user_id": "12345",
    "email": "[e-mail]"
  }
}

This payload notifies that an order was paid, including order details.

Rest API

{
  "event": "order.paid",
  "timestamp": "2024-06-01T15:30:00Z",
  "data": {
    "order_id": "98765",
    "amount": 49.99,
    "currency": "USD"
  }
}

Sample Program

This Python program creates a webhook payload with the event name, current time, and data, then prints it as formatted JSON.

Rest API

import json

def create_webhook_payload(event, data):
    from datetime import datetime, timezone
    payload = {
        "event": event,
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "data": data
    }
    return json.dumps(payload, indent=2)

# Example usage
payload_json = create_webhook_payload("user.created", {"user_id": "12345", "email": "[e-mail]"})
print(payload_json)

Important Notes

Always use a clear event name to describe what happened.

Use ISO 8601 format for timestamps to avoid confusion across time zones.

Keep the data section simple and only include necessary information.

Summary

Webhook payloads are JSON objects that tell another app about an event.

Include event name, timestamp, and data for clarity and usefulness.

Design payloads to be easy to read and parse by the receiving app.

Practice

1. What is the main purpose of a webhook payload in a REST API?

easy

A. To store user login credentials securely

B. To create a user interface for the API

C. To send event details from one app to another automatically

D. To encrypt data between client and server

Solution

1. Step 1: Understand webhook payload role

   A webhook payload is a message sent automatically when an event happens, sharing event details.

2. Step 2: Compare options with webhook purpose

   Only To send event details from one app to another automatically describes sending event details automatically, which matches webhook payload use.

3. Final Answer:

   To send event details from one app to another automatically -> Option C

4. Quick Check:

   Webhook payload = event details sent automatically [OK]

Hint: Webhook payloads always send event info automatically [OK]

Common Mistakes:

• Confusing payload with user authentication
• Thinking payload creates UI
• Assuming payload encrypts data

2. Which of the following is the correct JSON structure for a webhook payload that includes event name and timestamp?

easy

A. [ "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z" ]

B. { "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z" }

C. { event = "user_signup", timestamp = "2024-06-01T12:00:00Z" }

D. "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z"

Solution

1. Step 1: Identify valid JSON syntax

   JSON objects use curly braces {}, keys and values separated by colon :, keys in double quotes, and comma between pairs.

2. Step 2: Check each option's syntax

   { "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z" } uses correct JSON object syntax. [ "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z" ] uses square brackets which denote arrays, not key-value pairs. { event = "user_signup", timestamp = "2024-06-01T12:00:00Z" } uses equals sign instead of colon. "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z" is missing braces.

3. Final Answer:

   { "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z" } -> Option B

4. Quick Check:

   Valid JSON object = { "event": "user_signup", "timestamp": "2024-06-01T12:00:00Z" } [OK]

Hint: JSON objects use braces and colons, not brackets or equals [OK]

Common Mistakes:

• Using square brackets instead of braces for objects
• Using equals sign instead of colon
• Omitting braces around JSON

3. Given this webhook payload JSON:

{"event": "order_created", "timestamp": "2024-06-01T15:30:00Z", "data": {"order_id": 123, "amount": 49.99}}

What value will the receiving app find for data.amount?

medium

A. 49.99

B. order_created

C. "amount"

D. 123

Solution

1. Step 1: Locate the data.amount field in JSON

   Inside the "data" object, the key "amount" has the value 49.99 (a number).

2. Step 2: Match the value to options

   49.99 matches the numeric value 49.99. Other options are either keys or unrelated values.

3. Final Answer:

   49.99 -> Option A

4. Quick Check:

   data.amount = 49.99 [OK]

Hint: Look inside nested 'data' object for 'amount' key [OK]

Common Mistakes:

• Confusing order_id with amount
• Selecting string key instead of value
• Choosing event name instead of data field

4. You receive this webhook payload:

{"event": "payment_failed", "timestamp": "2024-06-01T16:00:00Z", "data": {"payment_id": 789}}

What is wrong with this payload?

medium

A. Payment ID should be a string, not a number

B. Timestamp format is incorrect

C. Event name should be inside data object

D. Missing closing brace for the JSON object

Solution

1. Step 1: Check JSON completeness

   The payload ends without a closing brace '}' for the outermost JSON object, making it invalid JSON.

2. Step 2: Verify other parts

   Timestamp format is ISO 8601 and correct. Event name is correctly outside data. Payment ID can be number or string depending on design.

3. Final Answer:

   Missing closing brace for the JSON object -> Option D

4. Quick Check:

   JSON must have matching braces [OK]

Hint: Always check for matching braces in JSON payloads [OK]

Common Mistakes:

• Ignoring missing braces
• Assuming timestamp format is wrong
• Thinking event must be inside data

5. You want to design a webhook payload for a "user_deleted" event that includes the user ID and deletion reason. Which JSON payload design is best for clarity and easy parsing?

hard

A. { "event": "user_deleted", "timestamp": "2024-06-01T17:00:00Z", "data": { "user_id": 456, "reason": "requested by user" } }

B. { "user_deleted": true, "user": 456, "reason": "requested by user" }

C. { "event": "user_deleted", "user_id": 456, "reason": "requested by user" }

D. { "event": "user_deleted", "timestamp": "2024-06-01T17:00:00Z", "user": { "id": 456, "reason": "requested by user" } }

Solution

1. Step 1: Check for standard webhook fields

   { "event": "user_deleted", "timestamp": "2024-06-01T17:00:00Z", "data": { "user_id": 456, "reason": "requested by user" } } includes event name, timestamp, and a nested data object holding user_id and reason, which is clear and standard.

2. Step 2: Compare other options for clarity and parsing

   { "user_deleted": true, "user": 456, "reason": "requested by user" } lacks event and timestamp keys properly named. { "event": "user_deleted", "user_id": 456, "reason": "requested by user" } mixes data fields at root level, less organized. { "event": "user_deleted", "timestamp": "2024-06-01T17:00:00Z", "user": { "id": 456, "reason": "requested by user" } } nests reason inside user object, which is less intuitive.

3. Final Answer:

   { "event": "user_deleted", "timestamp": "2024-06-01T17:00:00Z", "data": { "user_id": 456, "reason": "requested by user" } } -> Option A

4. Quick Check:

   Standard event + timestamp + data object = { "event": "user_deleted", "timestamp": "2024-06-01T17:00:00Z", "data": { "user_id": 456, "reason": "requested by user" } } [OK]

Hint: Use event, timestamp, and data object for clear payloads [OK]

Common Mistakes:

• Omitting timestamp
• Mixing data fields at root level
• Nesting unrelated fields inside user