Webhooks

Webhooks allow you to receive real-time notifications when events occur in the PerformID Network system. In addition to polling our API for changes, you can configure webhooks to send HTTP POST requests to your server when specific events happen.

How Webhooks Work

You register a webhook URL in the PerformID Network admin panel
When an event occurs (e.g. a new or updated payment), PerformID Network sends an HTTP POST request to your URL
Your server receives the event data and processes it
Your server responds with a 2xx status code to acknowledge receipt

Registering a Webhook

Webhooks can be registered through the PerformID Network admin panel.

Go to Headless API -> Webhooks
Click Add Webhook
Fill in the webhook details then click Save

The following fields are required when creating a webhook:

Webhook Type: The type of event you want to receive
Description: Notes about the webhook's purpose
URL: The HTTPS endpoint where you want to receive webhook events.

Enabling/Disabling a Webhook

You can enable or disable a webhook at any time from the admin panel. Check the Enabled box to activate the webhook, or uncheck it to deactivate.

Webhook Event Payload

When an event occurs, PerformID Network sends a POST request to your webhook URL with a JSON payload.

All webhook payloads include these standard fields as metadata:

event_id: A unique UUID for this event (used for idempotency)
event_type: The type of event (Refer to Webhook events)

Example:

{
  "data": [...],
  "meta": {
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "NEW_OR_UPDATED_REWARD",
  }
}

Webhook Events

When registering a webhook, the selected event type determines

New or Updated Reward Event

This event is triggered whenever there is a new or updated reward.

The payload will have the following structure:

data: An object containing the reward details. This includes all fields defined in the Reward Schema.
meta: An object containing metadata about the event. The event_type will be NEW_OR_UPDATED_REWARD.

Example:

{
  "data": {
    "reward_id": "123e4567-e89b-12d3-a456-426614174000",
    "amount": "10.000",
    "status": "SENT",
    "created_at": "2026-01-01T12:00:00Z",
    "updated_at": "2026-01-01T12:00:00Z",
    "currency_code": "USD",
    "sent_datetime": "2026-01-01T12:00:00Z"
  },
  "meta": {
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "NEW_OR_UPDATED_REWARD",
  }
}

Testing Your Webhook

Once you've registered a webhook, you should test it to ensure it's working correctly. The admin panel provides a convenient way to test your webhook:

Open your webhook in the admin panel
Click the Send Test Event button
A sample event of the selected type will be sent to your webhook URL
Check your server logs to confirm the event was received
View the event details and delivery attempts in the Webhook events section

Error Handling and Retries

If your webhook endpoint fails to respond or returns an error:

PerformID Network will retry the event up to 3 times with exponential backoff:

First retry: 1 minute after initial failure
Second retry: 5 minutes after second failure

After 3 failed attempts, the event status is marked as ERROR.

Monitoring Webhook Events

All webhook events and their delivery statuses can be monitored in the admin panel. For each event, you can see:

Status: PENDING, SENT, or ERROR
Event ID: Unique identifier for idempotency
Payload: The JSON data sent to your server
Errors: Number of failed delivery attempts

In addition, each delivery attempt is logged separately, with the following details:

Timestamp: When the attempt was made
Response Code: HTTP status code returned by your server
Error Message: Any error message returned (if applicable)

Resending Failed Events

Failed events are not automatically retried after reaching ERROR status. Use the Retry Sending button beside each failed event to set the status back to PENDING. Doing so will let the system attempt to send the webhook event again.

Security

Webhook Signatures (Planned)

Future versions will include:

Signature Header: Each webhook request will include a signature in the request headers
Verification Process: You'll be able to verify the signature using a shared secret
Timestamp Validation: Prevent replay attacks by validating the request timestamp

Best Practices

Respond Quickly: Return a 2xx response as quickly as possible. If processing takes time, acknowledge receipt immediately and queue the work for later processing.
Validate the payload: Verify the event data before processing
Be Idempotent: The same event may be delivered more than once. Use the event_id field to track which events you've already processed and avoid duplicate processing.
Log Everything: Keep detailed logs of webhook events for debugging
Test Thoroughly: Use the test event feature before going live