Webhook Subscriptions¶

This guide explains how SkillMeat uses GitHub webhooks to detect upstream changes, understand the three subscription states, and troubleshoot subscription issues.

Overview¶

Webhooks are the mechanism that enables SkillMeat to detect when upstream GitHub repositories release new versions. When you import an artifact from a GitHub marketplace source:

SkillMeat attempts to subscribe to that repository's webhook events
GitHub notifies SkillMeat when new releases are published
You see "Update available" in the web UI
You manually pull the update when ready (discovery-driven, not forced)

Key principle: Webhooks are advisory—they notify you of upstream activity but never automatically sync your artifacts.

Webhook Subscription States¶

Each marketplace source has a webhook subscription status that indicates whether automatic change detection is working.

Subscription States¶

1. `subscribed`¶

Status: ✅ Active and working

What it means: - Webhook is successfully registered with GitHub - SkillMeat is receiving notifications of upstream changes - You will see "Update available" badges when new releases occur

Next steps: - Normal operation - Check version history for "Update available" notifications - Pull updates when ready

Example:

Marketplace Source: anthropics/anthropic-quickstarts

Webhook Status: ✅ subscribed
  Last event: 2026-05-28 14:30 UTC
  Latest release detected: v2.1.0

2. `skipped`¶

Status: ⚠️ Webhook registration was skipped

What it means: - Webhook subscription was intentionally not attempted - Reasons include: - Source doesn't support webhooks (e.g., local-only source) - Webhooks disabled in source configuration - Manual update checking is preferred

Next steps: - You must manually check for upstream updates - No automatic notifications will appear - Consider enabling webhooks if the source supports it

Example:

Marketplace Source: my-internal-artifacts (local)

Webhook Status: ⚠️ skipped
  Reason: Source type does not support webhooks
  Next action: Manual check via marketplace source details

3. `failed`¶

Status: ❌ Subscription attempt failed

What it means: - SkillMeat tried to register a webhook but encountered an error - Common causes: - GitHub PAT lacks admin:repo_hook scope - User lacks repository write permissions - Repository settings don't allow webhooks - Network/API errors during registration

Next steps: - Review the error message (see Troubleshooting below) - Fix the root cause (permission, scope, or config) - Manually retry subscription - Fallback to manual update checking

Example:

Marketplace Source: anthropics/anthropic-quickstarts

Webhook Status: ❌ failed
  Error: Permission denied - user lacks write access to repository
  First attempt: 2026-05-27 10:15 UTC
  Next action: Check GitHub permissions or use different PAT

How Webhook Subscriptions Work¶

Registration Flow¶

When you import an artifact:

1. You click "Import from GitHub" or "Install from Marketplace"
2. SkillMeat creates a binding to the source
3. SkillMeat attempts to register a webhook with GitHub
   ├─ If successful → Status = "subscribed"
   ├─ If skipped → Status = "skipped"
   └─ If failed → Status = "failed"
4. Your artifact is imported
5. Future upstream changes trigger webhook notifications

Webhook Notification Flow¶

When upstream publishes a release:

GitHub Release published (v2.1.0)
  ↓
GitHub sends webhook notification → SkillMeat API
  ↓
SkillMeat receives event
  ├─ Updates release list for source
  ├─ Sets update_available = true for bindings
  └─ Triggers notification in web UI
  ↓
You see "Update available" badge in web UI
  ↓
You click "Pull Latest" to sync artifact
  ↓
Artifact advances to v2.1.0 (or policy-selected version)

Key point: The webhook sets the update_available flag. The actual sync is triggered by your action, not the webhook.

GitHub Requirements¶

Required Scope: `admin:repo_hook`¶

To register webhooks, your GitHub Personal Access Token (PAT) or GitHub App must include the admin:repo_hook scope.

Checking your PAT scope:

Go to GitHub Settings > Developer Settings > Personal Access Tokens
Click your token
Look for admin:repo_hook in the scopes list
If missing, regenerate with the correct scope

Example PAT with correct scope:

Token: ghp_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567
Scopes:
  ✅ repo (full repository access)
  ✅ admin:repo_hook (webhook management)
  ✅ read:user
  ✅ user:email

Repository Permissions¶

Your GitHub account must have write access (or higher) to the target repository:

Permission Level	Can Register Webhooks
Owner	✅ Yes
Collaborator (write)	✅ Yes
Collaborator (read)	❌ No
Outside collaborator	❌ No
Public repository (no access)	❌ No

Checking repository permissions:

Go to the repository on GitHub
Click "Settings" (if you have access)
Look for your username in Collaborators
Verify permission level is "Write" or higher

Checking Webhook Status¶

In the Web UI¶

Open Marketplace section
Find the source you want to check
Click on source details
Look for "Webhook Status" or "Subscription Status" section

Status display:

Marketplace Source Details: anthropics/anthropic-quickstarts

Webhook Status
├─ Status: ✅ subscribed
├─ Last event: 2026-05-28 14:30 UTC
├─ Latest release: v2.1.0 (detected 2026-05-28)
└─ Events received: 23

Via CLI¶

List all sources with webhook status:

skillmeat marketplace-sources --details

Output:

ID                          Repo                               Webhook Status   Last Event
src_anthropics_quickstart   anthropics/anthropic-quickstarts   subscribed       2026-05-28
src_internal_tools          miethe/internal-tools              failed           2026-05-27
src_community_skills        community/skill-library            subscribed       2026-05-29

Check specific source:

skillmeat marketplace-sources info <source_id>

Setting Up Webhooks¶

Prerequisites¶

✅ GitHub PAT or GitHub App with admin:repo_hook scope
✅ Write access to the target repository
✅ SkillMeat server accessible from GitHub (for webhook delivery)
✅ Webhook delivery enabled in repository settings

Automatic Setup (Recommended)¶

When you import an artifact from a GitHub source, SkillMeat automatically attempts to register a webhook:

skillmeat marketplace-install <bundle-id>

SkillMeat will:

Create a binding to the source
Try to register a webhook with GitHub using your PAT
Report success or failure in the UI

If subscription fails: - See Troubleshooting section below - Or manually set up webhook (see Manual Setup below)

Manual Setup¶

If automatic setup failed, you can manually register the webhook:

Via CLI:

skillmeat webhook-subscribe <source_id> --token <github-pat>

Via Web UI:

Go to Marketplace > Source Details
Click "Settings"
Click "Register Webhook"
Provide your GitHub PAT (or it will use your configured token)
Click "Subscribe"

GitHub side (manual verification):

Go to your GitHub repository
Click Settings > Webhooks
Look for webhook to https://your-skillmeat-instance/api/v1/webhooks/github/<connection_id>
Check "Deliveries" tab to verify recent successful deliveries

Webhook Payload & Events¶

What SkillMeat Listens For¶

SkillMeat listens for the following GitHub webhook events:

Event	Triggers When	Action
`release` (published)	New release published	Update available flag set
`release` (edited)	Release details updated	Release list refreshed
`push`	Code pushed to monitored branch	Checked for version changes

Example Webhook Payload¶

When GitHub publishes a release:

{
  "action": "published",
  "release": {
    "id": 12345678,
    "tag_name": "v2.1.0",
    "name": "Version 2.1.0",
    "draft": false,
    "prerelease": false,
    "published_at": "2026-05-28T14:30:00Z",
    "body": "## Changes\n- New feature X\n- Bug fix Y"
  },
  "repository": {
    "full_name": "anthropics/anthropic-quickstarts"
  }
}

SkillMeat processes:

Extracts release info (tag, name, date, prerelease status)
Updates the source's release list
Compares with pinned version
Sets update_available = true if newer version exists
Triggers "Update available" notification in UI

Troubleshooting¶

Issue: Webhook Status is "failed"¶

Common causes and solutions:

Cause 1: Missing `admin:repo_hook` scope¶

Error message: "Permission denied: admin:repo_hook scope required"

Solution:

# 1. Go to GitHub Settings > Developer Settings > Personal Access Tokens
# 2. Generate a NEW token with these scopes:
#    - repo (full control of private repositories)
#    - admin:repo_hook (manage repository hooks)
#    - read:user
#    - user:email

# 3. Configure SkillMeat with the new token:
skillmeat config set github-token ghp_YOUR_NEW_TOKEN_HERE

# 4. Retry webhook subscription:
skillmeat webhook-subscribe <source_id>

Cause 2: Insufficient repository permissions¶

Error message: "Permission denied: user lacks write access to repository"

Solution:

# 1. Ask repository owner to grant you write access
#    (or admin access if you need to manage other settings)

# 2. Once access is granted, retry:
skillmeat webhook-subscribe <source_id>

# 3. If it's a public repository you can't write to, consider:
#    - Using track_tags or snapshot_on_change policies
#    - Requesting maintainer to set up webhook on their side

Cause 3: Repository has webhooks disabled¶

Error message: "Webhooks are not allowed for this repository"

Solution:

# 1. Ask repository owner to enable webhooks in:
#    Settings > Security > Webhooks

# 2. Or use manual update checking instead:
#    - Use snapshot_on_change pin policy
#    - Check for updates manually from marketplace UI

Issue: Webhook status is "subscribed" but no updates appear¶

Possible causes and solutions:

Cause 1: Webhook deliveries failing¶

Solution:

Go to GitHub repo > Settings > Webhooks
Find the webhook for https://your-skillmeat-instance/api/v1/webhooks/...
Click "Deliveries" tab
Check recent deliveries — look for red X marks (failures)
Click a failed delivery to see error details

Common delivery failures:

Error	Fix
"Connection timeout"	Check SkillMeat server is accessible from GitHub
"404 Not Found"	Webhook URL may be stale; re-register
"500 Server Error"	Check SkillMeat logs for API errors

Cause 2: Release doesn't match filter criteria¶

Solution:

Check if the new release is a draft or prerelease
Your pin policy may filter these out:
track_latest_release skips drafts and prereleases
snapshot_on_change shows all releases
Check marketplace source details to see detected releases

Cause 3: Binding not linked to source with webhook¶

Solution:

Check artifact binding details
Verify it points to a source with status = subscribed
If not, recreate the binding with the correct source

Issue: Webhook status changed from "subscribed" to "failed"¶

Possible causes:

GitHub account permissions changed (lost write access)
PAT expired or was revoked
Repository settings changed (webhooks disabled)
SkillMeat server became unreachable

Solution:

Regenerate your GitHub PAT with correct scopes
Configure SkillMeat with new token: skillmeat config set github-token <new-token>
Re-subscribe: skillmeat webhook-subscribe <source_id>

Webhook Delivery & Retry¶

Webhook Retry Policy¶

If a webhook delivery fails, GitHub automatically retries:

First retry: After ~10 seconds
Second retry: After ~2 minutes
Third retry: After ~4 minutes
Max retry window: 24 hours

SkillMeat will eventually receive the notification and process it.

Manual Redeliver¶

If webhook is stuck:

Go to GitHub repo > Settings > Webhooks
Click the webhook
Scroll to "Deliveries"
Find the failed delivery
Click the "Redeliver" button

Best Practices¶

1. Use a Service Account PAT¶

Create a dedicated GitHub account for SkillMeat integrations:

# Good:
skillmeat config set github-token ghp_skillmeat_service_account_token

# Avoid:
# Personal token tied to individual developer accounts

Benefits: - Persist across team member changes - Clear audit trail - Permissions managed independently

2. Monitor Webhook Status Regularly¶

Set a reminder to check webhook subscriptions:

# Monthly check:
skillmeat marketplace-sources --details | grep "failed"

Alert if any show failed status.

3. Test Webhook After Setup¶

After setting up a webhook, trigger a test release:

Go to GitHub repo
Create a test release (e.g., v0.0.0-test)
Check SkillMeat within 1 minute for "Update available" notification
Verify release appears in source details
Delete the test release

4. Use Appropriate Pin Policies¶

If webhooks are problematic in your environment:

No webhooks available:
  └─ Use: snapshot_on_change or manual_pin
  └─ Manual monitoring instead of automatic

Webhooks working:
  └─ Use: track_latest_release or track_tags
  └─ Benefit from automatic change detection

Pin Policy Reference — How policies interact with webhooks
GitHub App Setup — Setting up GitHub App authentication
GitHub Authentication — Managing GitHub tokens
Marketplace Full Guide — Complete marketplace workflow

Webhook Subscriptions¶

Overview¶

Webhook Subscription States¶

Subscription States¶

1. subscribed¶

2. skipped¶

3. failed¶

How Webhook Subscriptions Work¶

Registration Flow¶

Webhook Notification Flow¶

GitHub Requirements¶

Required Scope: admin:repo_hook¶

Repository Permissions¶

Checking Webhook Status¶

In the Web UI¶

Via CLI¶

Setting Up Webhooks¶

Prerequisites¶

Automatic Setup (Recommended)¶

Manual Setup¶

Webhook Payload & Events¶

What SkillMeat Listens For¶

Example Webhook Payload¶

Troubleshooting¶

Issue: Webhook Status is "failed"¶

Cause 1: Missing admin:repo_hook scope¶

Cause 2: Insufficient repository permissions¶

Cause 3: Repository has webhooks disabled¶

Issue: Webhook status is "subscribed" but no updates appear¶

Cause 1: Webhook deliveries failing¶

Cause 2: Release doesn't match filter criteria¶

Cause 3: Binding not linked to source with webhook¶

Issue: Webhook status changed from "subscribed" to "failed"¶

Webhook Delivery & Retry¶

Webhook Retry Policy¶

Manual Redeliver¶

Best Practices¶

1. Use a Service Account PAT¶

2. Monitor Webhook Status Regularly¶

3. Test Webhook After Setup¶

4. Use Appropriate Pin Policies¶

Related Guides¶

1. `subscribed`¶

2. `skipped`¶

3. `failed`¶

Required Scope: `admin:repo_hook`¶

Cause 1: Missing `admin:repo_hook` scope¶