GREENGAGE API Webhook Documentation

This guide provides examples for integrating with the GREENGAGE API webhook system to create and manage missions programmatically.

Prerequisites

Before you begin, ensure you have:

• A valid GREENGAGE API secret key
• Access to the GREENGAGE API v2 endpoints
• Basic understanding of REST APIs and webhooks

⚠️ Important: Replace SECRET_KEY in all code examples with your actual API secret key.

Quick Start

1. Get Your Observatory ID

Since API v2, an observatory ID is required for all webhook submissions. Retrieve available observatories:

curl --location --request GET 'https://api-v2.greengage.dev/rest/observatories' \
--header 'Authorization: SECRET_KEY'

Response:

[
    {
        "id": "9e76a45c-5a3e-4fc0-8d61-cf39a56a7ee6",
        "name": "Test Observatory"
    }
]

2. Get Points of Interest (POI)

Missions require a poi_id parameter for display in the app. Fetch available POIs:

curl --location --request POST 'https://api-v2.greengage.dev/graphql' \
--header 'Authorization: SECRET_KEY' \
--header 'Origin: http://localhost:3000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "{ pois { id title } }",
    "variables": {}
}'

Creating Missions

Basic Mission Creation

Create a new mission using the webhook endpoint:

curl --location --request POST 'https://api-v2.greengage.dev/webhooks' \
--header 'Authorization: SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "origin": "mindearth",
    "type": "create",
    "data": {
        "name": "Sample Mission",
        "starting_point": [45.46464374888545, 9.18934835519496],
        "description": "A detailed description of the mission objectives and requirements.",
        "duration_min": 5,
        "distance_mt": 1200,
        "deeplink": "https://example.com/mission-details",
        "external_id": "unique-mission-id-18",
        "active": true,
        "poi_id": "778d6b3b-f1f6-4efc-a703-b687044e7f36",
        "observatory": "9e945d46-12be-483a-8862-92ad66010ccb"
    }
}'

Mission Parameters

Parameter	Type	Required	Description
name	string	✅	Mission title
starting_point	array	✅	GPS coordinates [latitude, longitude]
description	string	✅	Mission description
duration_min	integer	✅	Duration in minutes (alternative: duration)
distance_mt	integer	✅	Distance in meters
deeplink	string	✅	URL for additional mission details
external_id	string/integer	✅	Unique identifier from your system
active	boolean	✅	Mission availability status
poi_id	string	✅	Point of Interest UUID
observatory	string	✅	Observatory UUID
user_id	string	❌	Optional: GREENGAGE user identifier

Updating Mission Status

Update existing missions by referencing their external_id:

curl --location --request POST 'https://api-v2.greengage.dev/webhooks' \
--header 'Authorization: SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "origin": "mindearth",
    "type": "update",
    "data": {
        "external_id": "unique-mission-id-18",
        "status": "PENDING"
    }
}'

Available Status Values

• OPEN - Mission is available for users
• PENDING - Mission is in progress
• FAILED - Mission was not completed successfully
• FINISHED - Mission completed successfully

💡 Note: The update mechanism supports all properties from the create operation. You can update any mission field using the same structure.

Browser Implementation

HTML Example

For browser-based integration, see the included index.html example using Alpine.js and vanilla JavaScript.

Local Development

Run the HTML example locally:

# Install dependencies and start server
npm install
npm run start

# Alternative using http-server
npm install
npx http-server -p 3000

Integration Notes

• Replace SECRET_KEY in the HTML file with your actual API key
• The example uses Alpine.js for simplicity
• Ensure CORS is properly configured for production use

API Endpoints Reference

Endpoint	Method	Purpose
/webhooks	POST	Create or update missions
/graphql	POST	Query POIs and other data
/rest/observatories	GET	List available observatories

Error Handling

Common issues and solutions:

• Missing Observatory ID: Ensure you're using API v2 format with observatory parameter
• Invalid POI: Verify poi_id exists using the GraphQL endpoint
• Authentication: Check that your SECRET_KEY is valid and properly formatted
• CORS Issues: Ensure proper Origin headers for browser requests

Best Practices

1. Unique External IDs: Use consistent, unique identifiers for your missions
2. Validation: Validate GPS coordinates and required fields before sending
3. Error Handling: Implement proper error handling for API responses
4. Rate Limiting: Be mindful of API rate limits in production
5. Security: Never expose your SECRET_KEY in client-side code

Support

For additional help with the GREENGAGE API, consult the official documentation or contact the development team.