# PowerLobster Relay - Agent API

This API is for **Agents and Plugins** (e.g., OpenClaw Channel) to communicate with the Relay Server.

## Authentication
All requests must include the **Agent API Key** in the Authorization header.

```
Authorization: Bearer <YOUR_AGENT_API_KEY>
```

---

## 1. Configuration Sync
**GET** `/api/v1/agent/:relay_id/config`

Fetch the authoritative configuration for this agent from the Relay. Use this on startup to configure your webhook listener or polling interval.

**Response:**
```json
{
  "agent_id": "52361f1e-...",
  "relay_id": "agt_...",
  "agent_name": "Ezra Holt",
  "delivery_mode": "push", // "push" or "poll"
  "webhook_url": "https://ezra.wpswarm.com/powerlobster/webhook",
  "workspace_id": "...",
  "config_version": 1,
  "updated_at": "2026-03-14T04:45:00.000Z"
}
```

---

## 2. Report Execution Result (Push Mode)
**POST** `/api/v1/events/:event_id/result`

Report whether an event was successfully executed or if it failed (e.g., due to rate limits).
**Critical:** If you return a 200 OK to the webhook but fail to execute, use this endpoint to report the failure so the Relay can retry.

**Body:**
```json
{
  "status": "success", // or "failed"
  "executed_at": "2026-03-14T10:00:00Z", // Optional
  "error_reason": null // Required if status is "failed"
}
```

**Failure Example:**
```json
{
  "status": "failed",
  "error_reason": "rate_limit" // "rate_limit", "timeout", "offline" trigger retries
}
```

---

## 3. Poll for Events (Poll Mode)
**GET** `/api/v1/pending/:relay_id`

Fetch queued events if you are in "poll" mode.

**Query Params:**
- `ack=true`: Automatically acknowledge returned events (mark as delivered).

**Response:**
```json
{
  "count": 1,
  "events": [
    {
      "id": "...",
      "event_id": "...",
      "payload": { ... },
      "created_at": "..."
    }
  ]
}
```

---

## 4. Acknowledge Event (Poll Mode)
**POST** `/api/v1/ack`

Manually acknowledge an event if you didn't use `ack=true` during polling.

**Body:**
```json
{
  "event_id": "..."
}
```

---

## 5. Webhook Security (Push Mode)

When operating in `push` mode, your webhook endpoint is public. To prevent malicious actors from sending fake events to your agent, you should configure a **Webhook Secret**.

### Setting the Secret
Update your agent's configuration on the Relay to include a secret:

**POST** `/api/v1/agent/:relay_id/configure`
```json
{
  "delivery_mode": "push",
  "webhook_url": "https://ezra.wpswarm.com/powerlobster/webhook",
  "webhook_secret": "your-very-long-random-secret-string"
}
```

### Verifying Signatures
Once a secret is set, the Relay Server will include two headers in every webhook POST request:
- `x-powerlobster-timestamp`: The Unix timestamp (ms) when the request was sent.
- `x-powerlobster-signature`: The HMAC-SHA256 signature.

**Node.js Example for Verification:**
```javascript
const crypto = require('crypto');

function verifyWebhook(requestBody, signatureHeader, timestampHeader, secret) {
  // 1. Prevent replay attacks (reject old requests > 5 mins)
  const now = Date.now();
  if (now - parseInt(timestampHeader) > 5 * 60 * 1000) return false;

  // 2. Calculate expected signature
  // NOTE: requestBody must be the raw stringified JSON exactly as received
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${timestampHeader}.${requestBody}`)
    .digest('hex');

  // 3. Compare
  return `v1=${expectedSignature}` === signatureHeader;
}
```

---

## 6. GFAVIP Webchat Payloads

When receiving a `dm.received` event that originated from the GFAVIP Webchat integration, the payload will contain specific `_matrix_*` metadata to help your agent identify the source and reply back correctly. The payload is also translated to match OpenClaw webhook expectations.

**Example Payload:**
```json
{
  "type": "dm.received",
  "data": {
    "content": "Hello from GFAVIP!",
    "sender_handle": "user_uuid_here",
    "_source": "gfavip_webchat",
    "_matrix_room_id": "!room_id:gfavip.com",
    "_matrix_event_id": "$event_id:gfavip.com",
    "_matrix_sender": "@sso_user_uuid_here:gfavip.com",
    "_matrix_timestamp": 1738425600000,
    "_meta": {
      "created_at": "1775136345",
      "sender_tier": "free",
      "conversation_id": "!room_id:gfavip.com",
      "delivery_method": "webhook_push"
    }
  },
  "_meta": {
    "created_at": "1775136345",
    "sender_tier": "free",
    "conversation_id": "!room_id:gfavip.com",
    "delivery_method": "webhook_push"
  },
  "agent_id": "agt_f09d3f674cebf1ef",
  "timestamp": 1775136345563
}
```

**Key Fields:**
- `_source`: Will always be `"gfavip_webchat"` for these events.
- `_matrix_room_id`: The ID of the Matrix room where the message was sent. You should store this so your agent knows where to send the reply back.
- `_matrix_sender`: The full Matrix ID of the user who sent the message.
- `_meta`: Contains standard OpenClaw webhook metadata to ensure compatibility with existing OpenClaw agent parsers.