Integrations

Matchpal integrates with external services to handle purchases and email delivery. This guide covers how these integrations work and how to manage them.

Integration Overview

Matchpal connects with:

WooCommerce Integration

WooCommerce handles the commerce side of Matchpal—allowing students to purchase tutoring and advising packages.

How It Works

1. Student browses packages on WordPress/WooCommerce site
2. Student completes purchase
3. WooCommerce sends order data to Matchpal via webhook
4. Matchpal creates grant for the student
5. Student can begin matching process

Webhook Configuration

WooCommerce sends order notifications to Matchpal:

Webhook Events:

• order.completed - Successful purchase
• order.refunded - Refund processed

Webhook URL: Configure in WooCommerce to point to your Matchpal instance:

https://your-matchpal-domain/api/webhooks/woocommerce

Product Mapping

Each WooCommerce product needs to map to a Matchpal package:

Order Processing

When an order arrives:

1. Matchpal validates the webhook signature
2. Looks up customer by email
3. Creates or updates student account
4. Identifies product(s) purchased
5. Creates appropriate grant(s)
6. Logs the fulfillment

Handling Failures

If order processing fails:

• Error logged in order_fulfillment_error table
• Admin notified of failure
• Manual intervention may be required

Common failure reasons:

• Unknown product (no mapping configured)
• Invalid customer data
• Duplicate order processing
• Network/connectivity issues

See Order Errors for troubleshooting.

Testing the Integration

To verify WooCommerce connection:

1. Create a test order in WooCommerce
2. Check Matchpal for new grant
3. Verify student account created/updated
4. Review fulfillment logs

Resend Integration

Resend is the email delivery service that sends all Matchpal communications.

How It Works

1. Matchpal composes email from template
2. Sends to Resend API
3. Resend delivers to recipient
4. Resend sends status webhooks back to Matchpal
5. Email logs updated with delivery status

API Configuration

Matchpal connects to Resend using:

• API Key - Authenticates requests
• Domain - Verified sending domain
• From Address - Default sender address

Webhook Events

Resend notifies Matchpal of email events:

Webhook URL

Configure in Resend dashboard:

https://your-matchpal-domain/api/webhooks/resend

Email Tracking

Through Resend webhooks, Matchpal tracks:

• Delivery success/failure
• Open rates
• Click-through rates
• Bounce reasons

Handling Bounces

When emails bounce:

1. Resend sends bounce webhook
2. Matchpal logs the failure
3. Email status updated to "Bounced"
4. Bounce reason recorded

For persistent bounces:

• Verify email address correct
• Contact recipient for alternative
• Consider removing invalid addresses

Testing the Integration

To verify Resend connection:

1. Send a test email from Matchpal
2. Check email logs for "Sent" status
3. Verify email received
4. Confirm status updates via webhooks

Managing Integrations

Viewing Integration Status

Check integration health:

1. Navigate to Settings → Integrations
2. See connection status for each service
3. View recent activity
4. Check error rates

Troubleshooting Connectivity

If integrations aren't working:

WooCommerce:

• Verify webhook URL is correct
• Check webhook secret matches
• Review WooCommerce webhook logs
• Test webhook delivery manually

Resend:

• Verify API key is valid
• Check sending domain is verified
• Review Resend dashboard for errors
• Test API connection

Security Considerations

API Keys:

• Store securely (environment variables)
• Rotate periodically
• Never commit to source control

Webhooks:

• Validate signatures
• Use HTTPS only
• Implement rate limiting
• Log all incoming requests

Adding New Integrations

Future integrations may include:

• Calendar systems (scheduling)
• Video conferencing (session delivery)
• Payment processors (direct billing)
• CRM systems (student management)

Contact your administrator about integration requirements.

Related Documentation

• Billing - How WooCommerce orders create grants
• Order Errors - WooCommerce troubleshooting
• Email System - How Resend delivers emails
• Email Failures - Email troubleshooting