Webmentions not appearing can be frustrating, but the issue usually falls into one of a few common categories. This guide will help you debug and fix the problem.

Quick Diagnostic Checklist

Before diving deep, check these basics:

• Is your Webmention endpoint discoverable?
• Is the endpoint URL returning 200/202 responses?
• Does the source page actually link to the target?
• Are you checking the right target URL (http vs https, trailing slash)?
• Have you waited long enough for async processing?

1. Endpoint Discovery Issues

Problem: Senders Can't Find Your Endpoint

Symptoms:

• No Webmentions received at all
• Works with Telegraph but not automatically
• Endpoint logs show no incoming requests

Check:

<!-- View source of your page -->
<link rel="webmention" href="https://yourdomain.com/webmention" />

Test endpoint discovery:

# Check HTML
curl -s https://yourdomain.com/your-post | grep webmention

# Check HTTP headers
curl -I https://yourdomain.com/your-post | grep -i link

Common Mistakes:

<!-- ❌ Wrong: Missing closing tag -->
<link rel="webmention" href="...">

<!-- ❌ Wrong: Typo in rel attribute -->
<link rel="web-mention" href="...">

<!-- ❌ Wrong: Relative URL that's incorrect -->
<link rel="webmention" href="/endpoint">

<!-- ✅ Correct: Absolute URL -->
<link rel="webmention" href="https://yourdomain.com/webmention">

Solution:

Ensure the link tag is in the <head> of every page:

<head>
  <link rel="webmention" href="https://yourdomain.com/webmention" />
</head>

2. Endpoint Not Responding

Problem: Endpoint Returns Errors

Symptoms:

• Senders receive 404, 500, or timeout errors
• Webmentions work sporadically
• Endpoint logs show errors

Test your endpoint:

curl -X POST https://yourdomain.com/webmention \
  -d "source=https://test.example.com" \
  -d "target=https://yourdomain.com/post"

Expected response:

HTTP/1.1 202 Accepted

or

HTTP/1.1 200 OK

Common Issues:

404 Not Found

Your endpoint route isn't registered:

// ❌ Wrong: No route handler
app.listen(3000);

// ✅ Correct: Route registered
app.post('/webmention', handler);
app.listen(3000);

405 Method Not Allowed

Endpoint doesn't accept POST:

// ❌ Wrong: Using GET
app.get('/webmention', handler);

// ✅ Correct: Using POST
app.post('/webmention', handler);

500 Internal Server Error

Check your error logs:

app.post('/webmention', async (req, res) => {
  try {
    // Your code
  } catch (error) {
    console.error('Webmention error:', error);
    res.status(500).send('Error');
  }
});

3. Verification Failures

Problem: Mentions Don't Pass Verification

Symptoms:

• Endpoint receives mentions but doesn't save them
• Test mentions work but real ones don't
• Mentions marked as "unverified"

Common Causes:

URL Mismatch

The target URL in the mention doesn't exactly match your page URL:

// Mention sent for:
target: "https://yourdomain.com/post"

// But your page URL is:
actual: "https://yourdomain.com/post/"  // Note trailing slash

Solution:

Normalize URLs before comparison:

function normalizeUrl(url) {
  const parsed = new URL(url);
  // Remove trailing slash
  parsed.pathname = parsed.pathname.replace(/\/$/, '');
  // Always use https if available
  if (parsed.protocol === 'http:') {
    parsed.protocol = 'https:';
  }
  return parsed.href;
}

// Then compare:
if (normalizeUrl(target) === normalizeUrl(yourPageUrl)) {
  // Match!
}

Link Not Found in Source

Your verification is too strict or the source page has issues:

Debug it:

async function debugVerification(source, target) {
  const response = await fetch(source);
  const html = await response.text();

  console.log('Looking for:', target);
  console.log('Page contains:', html.includes(target));

  // Try variants
  const variants = [
    target,
    target.replace('https://', 'http://'),
    target + '/',
    target.replace(/\/$/, '')
  ];

  variants.forEach(variant => {
    if (html.includes(variant)) {
      console.log('Found variant:', variant);
    }
  });
}

JavaScript-Rendered Links

The source page renders links with JavaScript after page load:

<!-- Server-rendered HTML doesn't include the link -->
<div id="content"></div>

<script>
  // Link added by JS
  document.getElementById('content').innerHTML =
    '<a href="target-url">Link</a>';
</script>

Solution:

Use a headless browser for verification:

const puppeteer = require('puppeteer');

async function verifyWithBrowser(source, target) {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto(source, { waitUntil: 'networkidle0' });

  const html = await page.content();
  await browser.close();

  return html.includes(target);
}

4. Async Processing Delays

Problem: Mentions Take Too Long to Appear

Symptoms:

• Mentions eventually appear but take hours
• Queue backlog building up
• Verification timing out

Check queue processing:

// Log queue length
console.log('Queue size:', await queue.count());

// Monitor processing time
queue.on('completed', (job, result) => {
  console.log(`Job ${job.id} completed in ${job.finishedOn - job.processedOn}ms`);
});

Common Issues:

Queue Not Processing

// ❌ Wrong: Queue defined but no worker
const queue = new Queue('webmentions');

// ✅ Correct: Worker processing jobs
const queue = new Queue('webmentions');
queue.process(async (job) => {
  await verifyAndStore(job.data);
});

Verification Timeouts

// Set reasonable timeouts
const response = await fetch(source, {
  timeout: 10000, // 10 second timeout
  headers: {
    'User-Agent': 'YourSite/1.0 Webmention'
  }
});

Rate Limiting

You're being rate-limited when fetching source pages:

// Add delays between requests
const delay = ms => new Promise(resolve => setTimeout(resolve, ms));

async function processWithDelay(mentions) {
  for (const mention of mentions) {
    await processMention(mention);
    await delay(1000); // Wait 1 second between requests
  }
}

5. Display Issues

Problem: Mentions Stored But Not Showing

Symptoms:

• Database has mentions
• They're verified
• But don't appear on page

Check:

Query Issues

// ❌ Wrong: Querying wrong target
const mentions = await db.mentions.find({
  target: 'https://yourdomain.com/post'
});

// But stored with trailing slash
// target: 'https://yourdomain.com/post/'

// ✅ Correct: Use LIKE or normalize
const mentions = await db.mentions.find({
  target: { $regex: normalizeUrl(pageUrl) }
});

Filtering Too Aggressive

// ❌ Wrong: Only showing approved, but nothing is approved
const mentions = await db.mentions.find({
  target: pageUrl,
  status: 'approved'  // Nothing has this status!
});

// ✅ Correct: Show verified mentions
const mentions = await db.mentions.find({
  target: pageUrl,
  verified: true
});

Client-Side Fetching Failed

// Check browser console
fetch(`/api/mentions?target=${pageUrl}`)
  .then(res => res.json())
  .then(data => {
    console.log('Mentions loaded:', data);
  })
  .catch(error => {
    console.error('Failed to load mentions:', error);
  });

6. Microformats Parsing

Problem: Mentions Show Without Metadata

Symptoms:

• Mentions appear but no author name/photo
• All mentions look the same
• Can't distinguish replies from likes

Debug:

const mf2 = require('microformats-parser');

async function debugParsing(url) {
  const response = await fetch(url);
  const html = await response.text();
  const parsed = mf2.get({ html, baseUrl: url });

  console.log('Parsed data:', JSON.stringify(parsed, null, 2));
}

Check source page has microformats:

<!-- Required: h-entry -->
<article class="h-entry">
  <!-- Required for author info -->
  <div class="p-author h-card">
    <span class="p-name">Author Name</span>
    <img class="u-photo" src="photo.jpg">
  </div>
  <!-- Required for content -->
  <div class="e-content">...</div>
</article>

7. CORS Issues

Problem: Browser Can't Fetch Mentions

Symptoms:

• Console shows CORS errors
• Works on server, fails in browser
• Cross-origin request blocked

Solution:

Add CORS headers to your API:

app.get('/api/mentions', (req, res) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'GET');
  res.json(mentions);
});

Or use CORS middleware:

const cors = require('cors');
app.use('/api/mentions', cors());

8. Testing Tools

Manual Testing

Webmentions.com - Our full-featured service for sending and testing: https://www.webmentions.com/

Webmention Rocks - Comprehensive test suite: https://webmention.rocks/

Telegraph - Alternative sending tool: https://telegraph.p3k.io/

Automated Testing

// Test your endpoint
async function testEndpoint() {
  const response = await fetch('https://yourdomain.com/webmention', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      source: 'https://test.example.com',
      target: 'https://yourdomain.com/post'
    })
  });

  console.log('Status:', response.status);
  console.log('Expected: 200 or 202');
}

9. Debugging Checklist

Work through this systematically:

# 1. Can endpoint be discovered?
curl -s https://yourdomain.com/post | grep webmention

# 2. Does endpoint respond?
curl -X POST https://yourdomain.com/webmention \
  -d "source=test" -d "target=test"

# 3. Check endpoint logs
tail -f /var/log/webmention.log

# 4. Test verification
node -e "require('./verify').test('source-url', 'target-url')"

# 5. Check database
psql -c "SELECT * FROM webmentions WHERE target LIKE '%your-post%'"

# 6. Test display
curl https://yourdomain.com/api/mentions?target=your-post

Common Solutions Summary

Still Stuck?

1. Check the IndieWeb chat: https://chat.indieweb.org/
2. Test at webmention.rocks: Validates your implementation
3. Use Webmentions.com: Isolate whether issue is receiving or displaying with our hosted service
4. Enable debug logging: Add verbose logging to track the flow

Most Webmention issues are simple configuration problems that can be fixed in minutes once identified!