Webhooks API Documentation

By integrating these webhooks, you can seamlessly extend Wallafan's capabilities into your own applications and services.

Wallafan Webhooks API Documentation

Overview

The Wallafan platform provides webhook functionality that allows you to receive real-time notifications whenever certain events occur in an account you own or manage. You can subscribe to specific triggers (events) and have Wallafan send a POST request with detailed data to your designated endpoint.

Currently, we support the following triggers:

• `new_follower`: When a new follower is gained.
• `new_post`: When a new post is created.
• `new_product`: When a new product is added to the shop.

By subscribing to these triggers, you can integrate Wallafan events into your own systems, allowing you to perform actions such as analytics, notifications, or any custom logic you require.

Authentication

All subscription and unsubscription API endpoints are protected by `auth:sanctum`. Make sure you include a valid authentication token in your requests.

Endpoints

Subscribe to a Webhook

Endpoint: `POST /api/webhooks/subscribe`

Authorization: Bearer token (Sanctum)

Description: Subscribes to a particular event trigger, associating a URL that Wallafan will send data to whenever the event occurs.

Request Body Parameters:

 url  (string, required): The fully qualified URL of the endpoint on your server where we should send event data. 

• zap_trigger (string, required): The trigger event name you want to subscribe to. Supported values are `new_follower`, new_post`, `new_product`.

Example Request:

bash

curl -X POST https://wallafan.com/api/webhooks/subscribe \ 
	-H "Authorization: Bearer YOUR_TOKEN_HERE" \ 
	-H "Content-Type: application/json" \ 
	-d '{ 
		"url": "https://your-webhook-server.com/endpoint", 
        "zap_trigger": "new_post" 
        }'

Example Response (200 OK):

json

{
"message":"Webhook subscribed successfully"
}

Unsubscribe from a Webhook

Endpoint: DELETE /api/webhooks/unsubscribe

Authorization: Bearer token (Sanctum)

Description: Unsubscribes a previously subscribed URL from receiving event notifications.

Request Body Parameters:

• url (string, required): The URL you want to unsubscribe.

Example Request:

bash

curl -X DELETE https://your-domain.com/api/webhooks/unsubscribe \ 
	-H "Authorization: Bearer YOUR_TOKEN_HERE" \ 
	-H "Content-Type: application/json" \ 
	-d '{ 
		"url": "https://your-webhook-server.com/endpoint" 
	}'

Example Response (200 OK):

json

{
"message":"Webhook unsubscribed successfully"
}

Event Payloads

When one of the subscribed triggers occurs, Wallafan will send a POST request to your provided webhook URL with a JSON payload. Below are the payload structures for each trigger:

new_follower Trigger

Description: Sent when a new follower is gained on the subscriber's account.

Payload Example:

json

{
	"platform": "Wallafan",
	"your_account": "account_username",
	"name": "follower_name",
	"username": "follower_username",
	"email": "follower_email_or_empty_if_not_visible",
	"twitter": "follower_twitter_handle",
	"instagram": "follower_instagram_handle",
	"discord": "follower_discord_username",
	"facebook": "follower_facebook_profile",
	"youtube": "follower_youtube_channel",
	"patreon": "follower_patreon_profile",
	"twitch": "follower_twitch_username",
	"tiktok": "follower_tiktok_username",
	"accepted_at": "2024-01-31"// YYYY-MM-DD format
}

new_post Trigger

Description: Sent when a new post is created on the subscriber's account.

Payload Example:

json

{
	"platform": "Wallafan",
	"id": 12345,
	"post_url": "https://wallafan.com/post/12345",
	"username": "author_username",
	"text_content": "This is the post text content.",
	"media_type": "image",      // or "video", or "No Media"
	"lock_type": "public",      // could be 'locked' or 'public'
	"is_pinned": "No",      // "Yes" if pinned, otherwise "No"
	"created_on": "2024-01-31",      // YYYY-MM-DD format
	"time": "02:15 PM"      // h:i A format
}

new_product Trigger

Description: Sent when a new product is added to the subscriber's shop.

Payload Example:

json

{
	"platform": "Wallafan",
	"your_account": "shop_owner_username",
	"product_id": 6789,
	"product_name": "Sample Product",
	"product_description": "A wonderful product description.",
	"product_price": "19.99",
	"product_stock": 50,
	"product_url": "https://wallafan.com/shop/product/shop_owner_username/6789-sample-product",
	"created_on": "2024-01-31",      // YYYY-MM-DD format
	"time": "10:30 AM"      // h:i A format
}

Handling the Webhook Requests

Your server endpoint should be prepared to:

• Accept POST requests.
• Parse the incoming JSON payload.
• Respond with a 2xx HTTP status code if received successfully.

If your endpoint is unavailable or returns a non-2xx status code, Wallafan will not automatically retry. You should ensure high availability or implement your own retry logic if necessary.

Error Handling

If any errors occur during subscription or unsubscription, the API will return a 4xx status code along with a JSON object describing the validation errors.

Example Error Response (422 Unprocessable Entity):

json

{
	"url":["The url field is required."],
	"zap_trigger":["The zap_trigger field is required."]
}

Summary

• Subscribe to event triggers by calling POST /api/webhooks/subscribe with your endpoint URL and the trigger you want.
• Unsubscribe by calling DELETE /api/webhooks/unsubscribe and providing the URL you want to remove.
• Receive Events at your specified endpoint with a rich JSON payload detailing the event.