← Back to Developer Portal

API Documentation

Everything you need to integrate with the Tampa.dev platform.

Webhooks

Webhooks let you receive real-time HTTP POST notifications when events occur on the platform. Register webhooks in the Developer Portal.

Event Types

Platform Events

Event TypeDescriptionAccess
dev.tampa.events.syncedEvents were synced from an upstream sourcePublic
dev.tampa.sync.completedA full platform sync completedPublic
dev.tampa.user.favorite_addedA user favorited a groupPublic
dev.tampa.user.favorite_removedA user unfavorited a groupPublic
dev.tampa.user.profile_updatedA user updated their profilePublic
dev.tampa.user.portfolio_item_createdA user added a portfolio itemPublic
dev.tampa.user.identity_linkedA user linked an identity providerAdmin only
dev.tampa.user.registeredA new user registeredAdmin only
dev.tampa.user.deletedA user deleted their accountAdmin only
dev.tampa.achievement.unlockedA user completed an achievementAdmin only
dev.tampa.badge.issuedA badge was awarded to a userAdmin only
dev.tampa.user.score_changedA user's XP score changedAdmin only
dev.tampa.user.loginA user logged inPublic
dev.tampa.user.followedA user followed another userPublic
dev.tampa.onboarding.step_completedA user completed an onboarding stepPublic
dev.tampa.onboarding.completedA user completed all onboardingAdmin only
dev.tampa.developer.api_token_createdA developer created an API tokenPublic
dev.tampa.developer.webhook_createdA developer created a webhookPublic
dev.tampa.developer.application_registeredA developer registered an OAuth appPublic
test.pingTest webhook deliveryPublic

Group Management Events

Event TypeDescriptionAccess
dev.tampa.group.createdA new group was createdAdmin only
dev.tampa.group.updatedA group's settings were updatedAdmin only
dev.tampa.group.member_addedA user was added to a groupPublic
dev.tampa.group.member_removedA user was removed from a groupPublic
dev.tampa.group.member_role_changedA member's role was changedPublic
dev.tampa.group.claimedA group was claimed by a userAdmin only
dev.tampa.group.creation_requestedA group creation request was submittedAdmin only

Group Badge Events

Event TypeDescriptionAccess
dev.tampa.group.badge_createdA group badge was createdAdmin only
dev.tampa.group.badge_updatedA group badge was updatedPublic
dev.tampa.group.badge_deletedA group badge was deletedAdmin only

Event Management Events

Event TypeDescriptionAccess
dev.tampa.event.createdA native event was createdPublic
dev.tampa.event.updatedAn event was updatedPublic
dev.tampa.event.cancelledAn event was cancelledPublic
dev.tampa.event.rsvpA user RSVP'd to an eventPublic
dev.tampa.event.rsvp_cancelledA user cancelled their RSVPPublic
dev.tampa.event.checkinA user checked in to an eventPublic

Admin-restricted events require an admin or superadmin role to subscribe. Regular users will receive a 403 error if they attempt to create webhooks for these event types.

Payload Format

Every webhook delivery sends a JSON payload with this structure:

{
  "id": "delivery-uuid",
  "type": "dev.tampa.events.synced",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": { ... }
}

Payload Schemas by Event Type

dev.tampa.events.synced

Fired when events are synced from an upstream source (e.g., Meetup, Eventbrite).

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.events.synced",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "source": "meetup",
    "eventsCount": 42,
    "groupSlug": "tampa-devs"
  }
}

dev.tampa.sync.completed

Fired when a full platform sync completes across all sources.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.sync.completed",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "totalEvents": 156,
    "totalGroups": 12,
    "duration": 4500
  }
}

dev.tampa.user.favorite_added

Fired when a user favorites a group.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.user.favorite_added",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "user-uuid",
    "groupSlug": "tampa-devs",
    "groupName": "Tampa Devs"
  }
}

dev.tampa.user.profile_updated

Fired when a user updates their profile (name, username, bio, social links, etc.).

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.user.profile_updated",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "user-uuid",
    "fields": ["username", "bio", "socialLinks"]
  }
}

dev.tampa.user.portfolio_item_created

Fired when a user adds a portfolio item.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.user.portfolio_item_created",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "user-uuid",
    "itemId": "item-uuid",
    "title": "My Project"
  }
}

Admin-Restricted Events

Payload schemas for admin-restricted event types (dev.tampa.user.identity_linked, dev.tampa.user.registered, dev.tampa.user.deleted, dev.tampa.achievement.unlocked, dev.tampa.badge.issued, dev.tampa.user.score_changed) are documented in the admin panel under Admin Docs.

Group Management Events

dev.tampa.group.created

Fired when a new native group is created.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.created",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "groupId": "group-uuid",
    "groupName": "My Group",
    "createdBy": "user-uuid"
  }
}
dev.tampa.group.updated

Fired when a group's settings are updated.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.updated",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "groupId": "group-uuid",
    "fields": ["name", "description", "tags"]
  }
}
dev.tampa.group.member_added

Fired when a user is added to a group.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.member_added",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "groupId": "group-uuid",
    "userId": "user-uuid",
    "role": "member",
    "addedBy": "manager-uuid"
  }
}
dev.tampa.group.member_removed

Fired when a user is removed from a group (or leaves voluntarily).

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.member_removed",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "groupId": "group-uuid",
    "userId": "user-uuid",
    "removedBy": "manager-uuid"
  }
}
dev.tampa.group.member_role_changed

Fired when a member's role is updated.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.member_role_changed",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "groupId": "group-uuid",
    "userId": "user-uuid",
    "oldRole": "member",
    "newRole": "manager",
    "changedBy": "owner-uuid"
  }
}
dev.tampa.group.claimed

Fired when a group is claimed via an invite link.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.claimed",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "groupId": "group-uuid",
    "userId": "user-uuid",
    "method": "invite",
    "autoApproved": true
  }
}
dev.tampa.group.creation_requested

Fired when a user submits a group creation or claim request.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.creation_requested",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "requestId": "request-uuid",
    "userId": "user-uuid",
    "groupName": "My New Group",
    "type": "creation"
  }
}

The type field is "creation" for new group requests or "claim" for ownership claim requests.

dev.tampa.group.badge_created

Fired when a group badge is created.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.group.badge_created",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "groupId": "group-uuid",
    "badgeId": "badge-uuid",
    "badgeSlug": "contributor",
    "badgeName": "Contributor"
  }
}

Event Management Events

dev.tampa.event.created

Fired when a native event is created.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.event.created",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "eventId": "event-uuid",
    "groupId": "group-uuid",
    "title": "Monthly Meetup",
    "startTime": "2026-02-15T18:30:00-05:00",
    "createdBy": "user-uuid"
  }
}
dev.tampa.event.updated

Fired when an event is updated.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.event.updated",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "eventId": "event-uuid",
    "groupId": "group-uuid",
    "fields": ["title", "description"],
    "updatedBy": "user-uuid"
  }
}
dev.tampa.event.cancelled

Fired when an event is cancelled.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.event.cancelled",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "eventId": "event-uuid",
    "groupId": "group-uuid",
    "title": "Monthly Meetup",
    "cancelledBy": "user-uuid"
  }
}
dev.tampa.event.rsvp

Fired when a user RSVPs to an event, or when a waitlisted user is promoted.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.event.rsvp",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "eventId": "event-uuid",
    "userId": "user-uuid",
    "status": "confirmed",
    "waitlistPosition": null
  }
}

When a waitlisted user is automatically promoted (because a confirmed user cancelled), the payload includes "promotedFromWaitlist": true.

dev.tampa.event.rsvp_cancelled

Fired when a user cancels their RSVP.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.event.rsvp_cancelled",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "eventId": "event-uuid",
    "userId": "user-uuid",
    "previousStatus": "confirmed"
  }
}
dev.tampa.event.checkin

Fired when a user checks in to an event.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.event.checkin",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "eventId": "event-uuid",
    "userId": "user-uuid",
    "checkinCodeId": "code-uuid",
    "method": "link"
  }
}

The method field indicates how the user checked in: link (clicked a URL), qr (scanned a QR code), or nfc (tapped an NFC tag).

dev.tampa.user.login

Fired when a user logs in.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.user.login",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "user-uuid",
    "daysSinceCreation": 42
  }
}

dev.tampa.user.followed

Fired when a user follows another user.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.user.followed",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "follower-uuid",
    "followedUserId": "followed-uuid"
  }
}

dev.tampa.developer.api_token_created

Fired when a developer creates an API token.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.developer.api_token_created",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "user-uuid",
    "tokenId": "token-uuid",
    "tokenName": "My API Token"
  }
}

dev.tampa.developer.webhook_created

Fired when a developer creates a webhook.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.developer.webhook_created",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "user-uuid",
    "webhookId": "webhook-uuid",
    "url": "https://example.com/webhook"
  }
}

dev.tampa.developer.application_registered

Fired when a developer registers an OAuth application.

{
  "id": "d1e2f3a4-...",
  "type": "dev.tampa.developer.application_registered",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "userId": "user-uuid",
    "clientId": "client-id",
    "appName": "My App"
  }
}

test.ping

Test event for verifying webhook connectivity. Sent via the "Send Test" button in the Developer Portal.

{
  "id": "d1e2f3a4-...",
  "type": "test.ping",
  "timestamp": "2026-01-29T12:00:00.000Z",
  "data": {
    "message": "Hello from Tampa.dev!"
  }
}

Headers

HeaderDescription
X-Webhook-SignatureHMAC-SHA256 signature: sha256=hex_digest
X-Event-TypeThe event type (e.g. dev.tampa.events.synced)
X-Delivery-IDUnique delivery identifier
Content-Typeapplication/json
User-AgentTampaDevs-Webhooks/1.0

Signature Verification

Verify the X-Webhook-Signature header by computing HMAC-SHA256 of the raw request body using your webhook secret:

const crypto = require('crypto');

function verifySignature(body, secret, signature) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Always verify signatures before processing webhook payloads to ensure they originated from Tampa.dev.

Testing Webhooks

You can send test deliveries from the Developer Portal. The test UI lets you select a specific event type to simulate, generating a realistic payload for that event type. This helps you verify your webhook handler processes each event type correctly.

Retry Policy

If your endpoint returns a non-2xx status code or fails to respond, delivery is retried up to 3 times with exponential backoff. You can view delivery history in the Developer Portal.

← PreviousError CatalogNext →Examples