Definition
A webhook payload is the data sent from a source system to a subscriber's endpoint via an HTTP POST request when a specific event occurs. It serves as the core data package containing event-specific information.How It Works
- 1An application or service (source) is set up to send a webhook when a certain event happens.
- 2The source formats a payload, which is a structured data package, often in JSON format.
- 3This payload is sent as part of an HTTP POST request to the subscriber's endpoint (a URL set up to receive the webhook).
- 4The receiving system processes the payload to perform actions or trigger additional workflows.
Key Characteristics
- Format: Typically JSON, sometimes XML.
- Data Contents: Includes details about the event, such as the type of event, timestamp, and any relevant metadata.
- Real-Time: Delivered immediately when the event occurs, enabling real-time updates.
Comparison
| Concept | Description |
|---|---|
| Webhook Payload | Data sent during an HTTP POST request triggered by an event |
| API Request | Client-initiated request to retrieve or send data between systems |
| Event Notification | General alert about an event, may not include detailed data |
Real-World Example
A common example is GitHub sending a webhook payload to a CI/CD pipeline whenever code is pushed to a repository. The payload includes details about the commit, author, and files changed, enabling automated testing and deployment workflows.Best Practices
- Validation: Always verify payload signatures to ensure authenticity.
- Rate Limiting: Implement mechanisms to handle frequent payloads.
- Error Handling: Design systems to gracefully handle failed payload deliveries.
Common Misconceptions
- Webhook payloads are not emails: They are automated data transmissions, not messages you read.
- Not always JSON: While JSON is common, other formats like XML can be used.