Webhooks

Silver webhooks deliver real-time notifications to your application when events occur, such as when a claim adjudication completes.

How Webhooks Work

When an event occurs, Silver sends an HTTP POST request to your configured webhook URL with a JSON payload describing the event. Your endpoint should respond with a 2xx status code to acknowledge receipt.

Configuration

Webhook URLs are configured during onboarding. Contact your Silver representative to:

• Set or update your webhook endpoint URLs (multiple URLs per administrator are supported)
• Receive your webhook secret for authentication
• Configure which event types to receive

Authentication

Each webhook delivery includes your webhook secret in the apiKey header. Always verify this value matches your configured webhook secret before processing the payload.

from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "your-webhook-secret"

@app.route("/webhooks/silver", methods=["POST"])
def handle_webhook():
    # Verify the webhook secret
    if request.headers.get("apiKey") != WEBHOOK_SECRET:
        abort(403)

    event = request.json
    event_type = event.get("eventType")
    event_id = event.get("eventId")

    # Process the event...

    return "", 200

Idempotency

Each webhook delivery includes a unique eventId. You must deduplicate on eventId to handle the case where the same event is delivered more than once.

Store processed event IDs and check against them before processing:

processed_events = set()  # Use a database in production

def handle_event(event):
    event_id = event["eventId"]

    if event_id in processed_events:
        return  # Already processed, skip

    processed_events.add(event_id)
    # Process the event...

Delivery Guarantees

• The same event may be delivered more than once — for example, if the underlying adjudication task is retried. Always deduplicate on eventId.
• There are no dedicated webhook retries — if your endpoint is down when a delivery is attempted, that specific delivery will not be retried on its own.
• Use polling as a fallback to catch any missed webhook deliveries.

Payload Structure

All webhook payloads share a common structure:

{
  "eventId": "evt_unique_id",
  "eventType": "adjudication_complete",
  "eventPayload": {
    // Event-specific data — full claim details and adjudication results
  }
}

Field	Type	Description
eventId	string	Unique event identifier for idempotency
eventType	string	Type of event (e.g., adjudication_complete)
eventPayload	object	Event-specific payload

Available Events

Event Type	Description	Reference
adjudication_complete	A claim adjudication has completed	Adjudication Complete