moegoapis

Webhook API Documentation (moego.business.webhook.v1)

📌 1. Functional Overview

Webhook is a lightweight event notification mechanism that actively pushes data to a specified URL when certain business events occur. This interface enables:

🎯 2. Design Goals

Applicable to scenarios such as order status change notifications, user registration synchronization, exception alerts, and third-party system integration.

🧩 3. Core Concepts

1. Webhook

Represents a webhook subscription configuration, including the target URL, subscribed event types, authentication method, etc.

Field Name Type Description
id string Unique identifier
organizations Array(Organization) List of organizations
eventTypes Array(EventType) Subscribed event types
endpointUrl string URL to receive webhook
secretToken string Optional HMAC token
contentType ContentType Default is JSON
isActive bool Whether active
verifySsl bool Whether to verify SSL
headers map(string, HeaderValues) Custom HTTP headers
createdTime Timestamp Creation time
updatedTime Timestamp Last update time

2. Organization

Represents an organization entity in the MoeGo system. Organizations are the top-level grouping for resources and determine available features and capabilities.

Field Name Type Description
id string Unique identifier for the organization. The prefix should match the organization type:
- BUSINESS: Format “biz_” + random characters (e.g., “biz_id001”)
- COMPANY: Format “cop_” + random characters (e.g., “cop_id001”)
- ENTERPRISE: Format “ent_” + random characters (e.g., “ent_id001”)
type Type Organization’s service tier. Determines feature availability and API capabilities. Options:
- BUSINESS: Single-location business with standard features
- COMPANY: Multi-location business with advanced features
- ENTERPRISE: Enterprise organization with full platform access

Example:

{
  "organizations": [
    {
      "id": "cop_id001",
      "type": "COMPANY"
    },
    {
      "id": "biz_id001",
      "type": "BUSINESS"
    }
  ]
}

Usage in Webhooks: When specified in a webhook configuration, the webhook will only receive events from the listed organizations. If the organizations array is empty, the webhook receives events from all organizations accessible to the API key.

3. EventType

Event types categorize different kinds of events that can trigger webhook calls. Each event type corresponds to a specific business operation or system occurrence.

Event Type Ranges:

For detailed event structures and payloads, refer to event.proto.

4. HeaderValues

Represents a list of values for a custom HTTP header key. This allows webhooks to include multiple values for the same header when delivering payloads.

Field Name Type Description
values Array(string) List of values for the header key

Usage in Webhooks: Custom HTTP headers can be added to webhook delivery requests for authentication, identification, or other purposes. Each header key maps to a HeaderValues object containing one or more string values.

Example:

{
  "headers": {
    "Authorization": {
      "values": [
        "Bearer your_token"
      ]
    },
    "X-Custom-Header": {
      "values": [
        "value1",
        "value2"
      ]
    }
  }
}

5. WebhookDelivery

Represents a specific webhook push record.

By default, delivery logs are retained for up to 15 days

Field Name Type Description
id string Delivery log ID
webhookId string Associated webhook ID
eventType EventType Event type (see section 3 above)
eventId string Unique event ID
requestUrl string Request URL
deliveredTo string Actual destination address
requestHeaders map(string, HeaderValues) Request headers (see section 4)
requestBody bytes The request body encoded in base64
responseStatus int32 HTTP status code
responseHeaders map(string, HeaderValues) Response headers (see section 4)
responseBody bytes The Response body encoded in base64
deliveredAt Timestamp Delivery timestamp
durationMs int64 Duration in milliseconds
success bool Whether successful
error string Error message
retryCount int32 Retry count
requestFormat ContentType Request format
responseFormat ContentType Response format

📈 5. Typical Usage Flow

✅ Scenario: User Integrates and Debugs Webhook

Here is a typical integration flow:

  1. Create Webhook
    • Specify endpoint URL and interested event types.
    • Set HMAC token, headers, etc.
  2. Trigger Test Call
    • Use TriggerTestWebhookDelivery to send a test event (e.g., ping).
    • Verify that the server receives the request.
  3. View Delivery Logs
    • Use ListWebhookDeliveries to view historical push records.
    • Analyze failure reasons (e.g., network errors, permission issues).
  4. Update/Delete Webhook
    • Modify endpoint or event_types.
    • Delete when no longer needed.
  5. Monitoring & Retrying
    • Regularly check delivery success rate.
    • Use RedeliverWebhookDelivery to retry failed deliveries.

📦 6. API Interface Descriptions

1. Create Webhook (CreateWebhook)

✅ Functionality:

Registers a new webhook, subscribes to specified event types, and configures the target URL and related parameters ( e.g., authentication token, headers).

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
endpointUrl string Yes URL to receive webhook
organizations Array(Organization) No Organization list (empty means all)
eventTypes Array(EventType) Yes List of event types (empty = none)
secretToken string No Optional HMAC token
contentType ContentType No Content format, default JSON
isActive bool No Whether active, default true
verifySsl bool No Whether to verify SSL (recommended)
headers map(string, HeaderValues) No Custom HTTP headers

💡 Example Request:

{
  "endpointUrl": "https://your-service.com/webhook",
  "organizations": [
    {
      "id": "cop_id001",
      "type": "COMPANY"
    }
  ],
  "eventTypes": [
    "APPOINTMENT_CREATED",
    "APPOINTMENT_FINISHED"
  ],
  "secretToken": "my-secret-token",
  "isActive": true,
  "verifySsl": true,
  "headers": {
    "Authorization": {
      "values": [
        "Bearer your_token"
      ]
    }
  }
}

📌 Return Value:

Field Name Type Description
webhook Webhook The created webhook object

⚠️ Error Codes:

Error Code Description
ALREADY_EXISTS A webhook with the same endpoint URL already exists
PERMISSION_DENIED Permission denied
INVALID_ARGUMENT Invalid request parameters
NOT_FOUND Specified organization does not exist
RESOURCE_EXHAUSTED Maximum webhook count reached

2. Get Webhook (GetWebhook)

✅ Functionality:

Retrieves a registered webhook’s full configuration, including subscribed event types, target address, and status.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
id string Yes Webhook ID to retrieve

📌 Return Value:

Field Name Type Description
webhook Webhook The retrieved webhook object

⚠️ Error Codes:

Error Code Description
NOT_FOUND Specified webhook ID does not exist
PERMISSION_DENIED Permission denied

3. Update Webhook (UpdateWebhook)

✅ Functionality:

Updates an existing webhook configuration, e.g., modify endpoint URL, adjust subscribed event types, update headers or secret token.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
id string Yes Webhook ID to update
endpointUrl string Yes New endpoint URL
organizations Array(Organization) No Updated organization list
eventTypes Array(EventType) Yes Updated event types
secretToken string No Updated secret token
contentType ContentType No Updated content type
isActive bool No Whether active
verifySsl bool No Whether to verify SSL
headers map(string, HeaderValues) No Custom HTTP headers

📌 Return Value:

Field Name Type Description
webhook Webhook The updated webhook object

⚠️ Error Codes:

Error Code Description
NOT_FOUND Specified webhook ID does not exist
PERMISSION_DENIED Permission denied

4. Delete Webhook (DeleteWebhook)

✅ Functionality:

Deletes a registered webhook and stops all its event pushes.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
id string Yes Webhook ID to delete

📌 Return Value:

Field Name Type Description
(empty) DeleteWebhookResponse Empty response on success

⚠️ Error Codes:

Error Code Description
NOT_FOUND Specified webhook ID does not exist
PERMISSION_DENIED Permission denied

5. List Webhooks (ListWebhooks)

✅ Functionality:

Lists all webhooks under the current account, supporting filtering by status, event types, and time range.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
pagination Pagination Yes Pagination info: pageSize, pageToken
filter.isActive bool No Filter by active status
filter.eventTypes Array(EventType) No Filter by event types
filter.createdTime Interval No Filter by creation time
filter.updatedTime Interval No Filter by update time

📌 Return Value:

Field Name Type Description
nextPageToken string Token for next page
webhooks Array(Webhook) List of matching webhook configurations

⚠️ Error Code:

Error Code Description
PERMISSION_DENIED Permission denied

6. Trigger Test Webhook (TriggerTestWebhookDelivery)

✅ Functionality:

Manually triggers a test event delivery to verify whether the webhook is working correctly. Sends a “ping” event by default.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
id string Yes Webhook ID to test
eventType EventType No Custom event type (default: PING)
payload bytes No Custom payload content

📌 Return Value:

Field Name Type Description
delivery WebhookDelivery The delivery log object

⚠️ Error Codes:

Error Code Description
NOT_FOUND Specified webhook ID does not exist
PERMISSION_DENIED Permission denied

7. Get Webhook Delivery Log (GetWebhookDelivery)

✅ Functionality:

Retrieves a specific webhook push record, including detailed request/response information.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
id string Yes Delivery log ID

📌 Return Value:

Field Name Type Description
delivery WebhookDelivery The retrieved delivery object

⚠️ Error Codes:

Error Code Description
NOT_FOUND Specified log ID does not exist
PERMISSION_DENIED Permission denied

8. List All Webhook Deliveries (ListWebhookDeliveries)

✅ Functionality:

Lists all push records for a given webhook, supports filtering by event type, success status, and time range.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
pagination Pagination Yes Pagination info
webhookId string Yes Associated webhook ID
filter.eventTypes Array(EventType) No Filter by event types
filter.success bool No Filter by success status
filter.deliveryTime Interval No Filter by delivery time range

📌 Return Value:

Field Name Type Description
nextPageToken string Token for next page
deliveries Array(WebhookDelivery) List of matching delivery objects

⚠️ Error Code:

Error Code Description
PERMISSION_DENIED Permission denied

9. Redeliver Webhook Delivery (RedeliverWebhookDeliveries)

✅ Functionality:

Retries a failed webhook delivery, useful after fixing endpoint issues.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
id string Yes Delivery log ID to retry
webhookId string Yes Associated webhook ID

📌 Return Value:

Field Name Type Description
delivery WebhookDelivery The redelivered delivery object

⚠️ Error Code:

Error Code Description
PERMISSION_DENIED Permission denied

🧪 7. Usage Examples

Example 1: Create Webhook

{
  "endpointUrl": "https://your-service.com/webhook",
  "organizations": [
    {
      "id": "cop_id001",
      "type": "COMPANY"
    },
    {
      "id": "biz_id001",
      "type": "BUSINESS"
    }
  ],
  "eventTypes": [
    "APPOINTMENT_CREATED",
    "CUSTOMER_CREATED"
  ],
  "secretToken": "my-secret-token",
  "isActive": true,
  "verifySsl": true,
  "headers": {
    "Authorization": {
      "values": [
        "Bearer your_token"
      ]
    }
  }
}

Example 2: Trigger Test Call

{
  "id": "whk_001",
  "eventType": "HEALTH_CHECK",
  "payload": "{ \"test\": \"hello world\" }"
}

Example 3: Query Delivery Logs

{
  "webhookId": "whk_001",
  "pagination": {
    "pageSize": 20,
    "pageToken": "1"
  },
  "filter": {
    "success": false,
    "deliveryTime": {
      "startTime": "2024-08-01T00:00:00Z",
      "endTime": "2024-08-02T00:00:00Z"
    }
  }
}

⚠️ 8. Usage Limitations

To ensure system stability and fair resource usage, the following default limits are applied to webhook usage:

1. Maximum Number of Webhook Configurations per Client

2. Maximum Pushes per Minute per Webhook

3. Daily Total Push Count per Webhook

4. Monthly Total Push Count per Webhook

5. Delivery Log Retention Period

⚠️ Note: If limits are exceeded, the API may return RESOURCE_EXHAUSTED. It is recommended that clients implement reasonable rate-limiting fallback logic, such as queue caching and delayed retries.

📎 9. FAQ

Question Answer
How to determine if a webhook is effective? Use TriggerTestWebhookDelivery to send a test and observe delivery logs
How to prevent duplicate webhooks? System automatically detects identical endpoint_url, returns ALREADY_EXISTS
What content formats does webhook support? Currently supports JSON, default CONTENT_TYPE_JSON
How to view failed records? Use ListWebhookDeliveries with filter.success = false
Can webhook limit events from specific companies or businesses? Yes, via the organizations field
Why does creating a webhook return “resource exhausted”? The client may have reached the maximum allowed webhook count. Clean up unused webhooks or contact admin to increase quota.
Why does webhook delivery fail with status RESOURCE_EXHAUSTED? Indicates push frequency or total volume has exceeded platform limits. Try again later or optimize push logic to avoid triggering rate limiting.

🛡️ 10. Security Recommendations

📌 11. Common Error Codes

Error Code Description
ALREADY_EXISTS A webhook with the same URL already exists
NOT_FOUND Webhook or delivery ID does not exist
PERMISSION_DENIED Current user has no access rights
INVALID_ARGUMENT Invalid request parameters
INTERNAL Internal server error
RESOURCE_EXHAUSTED Request exceeds system quota limits

📎 12. Related File References