Coming soon
Webhooks are under active development and not yet available in the PingRep API. This page outlines the planned design so you can prepare your integration ahead of time.
What are webhooks?
Webhooks let your application receive real-time HTTP notifications when events happen in PingRep. Instead of polling the API repeatedly to check for changes, you register a URL and PingRep sends a POST request to it whenever a relevant event occurs.
Planned events
The following webhook events are planned for the initial release:
| Event | Description |
|---|---|
profile.created | A new profile was created |
profile.updated | A profile was modified |
chat.message | A new message was sent to an AI Representative |
chat.lead_captured | The AI Representative captured contact information from a visitor |
subscription.created | A user subscribed to a paid tier |
subscription.cancelled | A subscription was cancelled |
subscription.renewed | A subscription was renewed for a new billing period |
organization.member_added | A new member joined an organization |
organization.member_removed | A member was removed from an organization |
Planned security model
All webhook deliveries will include a signature header for verification. This prevents attackers from sending fake events to your endpoint.
Signature verification (planned)
Each webhook delivery will include an X-PingRep-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.
Planned payload format
Webhook payloads will follow a consistent structure:
eventstringRequiredThe event type identifier (e.g., "profile.updated").
timestampstringRequiredISO 8601 timestamp of when the event occurred.
dataobjectRequiredEvent-specific payload. Structure varies by event type.
Delivery guarantees (planned)
- At-least-once delivery. Events may be delivered more than once. Your handler should be idempotent.
- Retry policy. Failed deliveries (non-2xx response) will be retried up to 5 times with exponential backoff.
- Timeout. Your endpoint must respond within 10 seconds or the delivery is considered failed.
- Ordering. Events are not guaranteed to arrive in order. Use the
timestampfield to determine sequence.
Preparing your integration
While webhooks are not yet available, you can prepare by:
- Designing your handler endpoint with signature verification from day one
- Making handlers idempotent so duplicate deliveries do not cause issues
- Returning 200 quickly and processing events asynchronously in a background queue
- Logging all received events for debugging and audit purposes
Get notified
Want to know when webhooks launch? Follow the Changelog or contact support@pingrep.com to join the early access list.