Home / Documentation / API & Developers / Webhooks

🔗 Webhooks

Set up real-time notifications and event-driven integrations with Sports Buddies webhooks for instant updates and seamless automation.

What are Webhooks?

Webhooks are HTTP callbacks that send real-time notifications to your application when specific events occur in Sports Buddies, enabling instant updates and automated workflows.

⚡ Real-time Updates

Receive instant notifications when events happen, eliminating the need for constant API polling.

Benefits:

  • Instant event notifications
  • Reduced API calls
  • Better user experience
  • Real-time synchronization

🔄 Event-Driven Architecture

Build responsive applications that react to user actions and system events automatically.

Benefits:

  • Automated workflows
  • Event-driven processing
  • Scalable architecture
  • Reduced latency

🔌 Easy Integration

Simple HTTP POST requests to your endpoint with detailed event data and metadata.

Benefits:

  • Standard HTTP protocol
  • JSON payload format
  • Secure authentication
  • Reliable delivery

Available Webhook Events

Subscribe to the events that matter most for your application and receive detailed payloads with relevant information.

👥 User Events

Notifications about user activities, profile changes, and account updates.

user.created

Triggered when a new user account is created

user.updated

Triggered when user profile information is modified

user.verified

Triggered when a user completes ID verification

user.deleted

Triggered when a user account is deleted

🎯 Matching Events

Updates about the BuddyMatch™ algorithm, connections, and compatibility scoring.

match.created

Triggered when a new match is created between users

match.accepted

Triggered when a user accepts a match request

match.declined

Triggered when a user declines a match request

match.expired

Triggered when a match request expires

📅 Event & Activity Events

Notifications about sports events, meetups, and community activities.

event.created

Triggered when a new sports event is created

event.updated

Triggered when event details are modified

event.rsvp

Triggered when users RSVP to events

event.cancelled

Triggered when an event is cancelled

💬 Communication Events

Updates about messaging, notifications, and user interactions.

message.sent

Triggered when a new message is sent

message.read

Triggered when a message is read

notification.sent

Triggered when a push notification is sent

notification.delivered

Triggered when a notification is delivered

Setting Up Webhooks

Follow these steps to configure webhooks for your application and start receiving real-time notifications.

Step-by-Step Setup Guide

1

Create Your Endpoint

Set up a public HTTP endpoint (URL) that can receive POST requests from Sports Buddies. This endpoint should be accessible from the internet and able to handle JSON payloads.

https://yourdomain.com/webhooks/sportsbuddies
2

Configure Webhook in Dashboard

Log into your Sports Buddies developer dashboard and navigate to the Webhooks section. Add your endpoint URL and select the events you want to subscribe to.

POST /api/v1/webhooks { "url": "https://yourdomain.com/webhooks/sportsbuddies", "events": ["user.created", "match.created", "event.created"] }
3

Verify Your Endpoint

Sports Buddies will send a verification request to your endpoint. Your server should respond with the verification token to confirm ownership and activate the webhook.

// Verify endpoint ownership if (request.body.challenge) { response.json({ challenge: request.body.challenge }); }
4

Handle Incoming Webhooks

Implement logic to process incoming webhook payloads. Verify the signature, parse the event data, and take appropriate actions in your application.

// Process webhook payload app.post('/webhooks/sportsbuddies', (req, res) => { const event = req.body; console.log('Received event:', event.type); // Handle event based on type res.status(200).send('OK'); });

Security & Authentication

Learn about the security measures we implement to ensure your webhooks are secure and authentic.

🔐

Signature Verification

Each webhook includes a cryptographic signature that you can verify to ensure the request came from Sports Buddies and hasn't been tampered with.

🔑

Webhook Secret

Use your unique webhook secret to verify the authenticity of incoming webhooks and prevent unauthorized access to your endpoint.

🌐

HTTPS Required

All webhook endpoints must use HTTPS to ensure secure transmission of sensitive data and prevent man-in-the-middle attacks.

📝

IP Whitelisting

Optionally restrict webhook delivery to specific IP addresses for additional security and control over who can send requests to your endpoint.

Testing & Debugging

Tools and techniques to help you test your webhook implementation and troubleshoot any issues.

Testing Tools & Methods

Webhook Testing Dashboard

Use our developer dashboard to send test webhooks to your endpoint and verify that your implementation is working correctly.

Open Dashboard View Documentation

Local Testing with ngrok

Test webhooks locally during development using ngrok to create a secure tunnel to your local development environment.

Download ngrok Setup Guide

Webhook Logs

View detailed logs of all webhook delivery attempts, including success/failure status, response codes, and error messages.

View Logs Log Format

Monitoring & Reliability

Track webhook delivery performance and ensure reliable notification delivery to your application.

📊

Delivery Statistics

Monitor webhook delivery rates, response times, and failure rates to ensure optimal performance.

🔄

Automatic Retries

Failed webhook deliveries are automatically retried with exponential backoff to maximize delivery success.

⚠️

Failure Notifications

Receive alerts when webhook delivery fails repeatedly, helping you identify and resolve issues quickly.

📈

Performance Metrics

Track response times, throughput, and other performance indicators to optimize your webhook handling.

Webhook Examples

See real examples of webhook payloads and learn how to handle different event types in your application.

User Created Event

This webhook is triggered when a new user account is created in Sports Buddies.

{ "id": "evt_1234567890", "type": "user.created", "created": "2025-01-15T10:30:00Z", "data": { "user": { "id": "usr_987654321", "email": "user@example.com", "username": "sportslover", "first_name": "John", "last_name": "Doe", "sports": ["basketball", "tennis"], "location": "New York, NY", "created_at": "2025-01-15T10:30:00Z" } } }

Match Created Event

This webhook is triggered when the BuddyMatch™ algorithm creates a new match between compatible users.

{ "id": "evt_1234567891", "type": "match.created", "created": "2025-01-15T11:00:00Z", "data": { "match": { "id": "mtch_555666777", "user1_id": "usr_987654321", "user2_id": "usr_111222333", "compatibility_score": 87, "common_sports": ["basketball"], "created_at": "2025-01-15T11:00:00Z" } } }

Event Created Event

This webhook is triggered when a user creates a new sports event or meetup.

{ "id": "evt_1234567892", "type": "event.created", "created": "2025-01-15T12:00:00Z", "data": { "event": { "id": "evt_888999000", "title": "Weekend Basketball Game", "description": "Casual pickup game at Central Park", "sport": "basketball", "location": "Central Park, NYC", "date": "2025-01-18T14:00:00Z", "max_participants": 10, "creator_id": "usr_987654321", "created_at": "2025-01-15T12:00:00Z" } } }

Explore More Documentation

Discover other helpful guides and resources to get the most out of Sports Buddies.

🎯 Getting Started

Learn the basics of Sports Buddies, create your profile, and make your first connection.

Quick Start Guide Profile Setup Making Connections App Navigation

📱 User Guides

Master all the features and learn how to get the most out of Sports Buddies.

BuddyMatch™ Algorithm Messaging & Communication Events & Meetups Notifications & Settings

🛡️ Safety & Trust

Learn about our PlaySafe™ features, verification process, and how we protect our community.

VerifiedPlayer™ ID Verification PlaySafe™ Safety Features Reporting Issues ShowScore™ Rating System

🤝 Community

Understand our community guidelines, moderation policies, and how to be a great community member.

Community Guidelines Moderation Policies Best Practices Community Events

⚙️ API & Developers

Technical documentation for developers, integrations, and API access.

API Overview Authentication API Endpoints Webhooks

❓ Help & Support

Find answers to common questions and get help when you need it.

Frequently Asked Questions Troubleshooting Contact Support Send Feedback

📋 Policies

Read our terms of service, privacy policy, and other important legal documents.

Terms of Service Privacy Policy Community Standards Data Usage Policy