Welcome to the Webmentions documentation! This guide will help you understand what Webmentions are and how to start using them on your website.

What are Webmentions?

Webmentions are a simple way to notify any URL when you mention it on your site. They're a W3C Recommendation that enables conversations and interactions across different websites.

Key Concepts

Source: The URL that contains the mention (your page)

Target: The URL being mentioned (someone else's page)

Endpoint: The URL that receives Webmention notifications

Why Use Webmentions?

Webmentions provide several benefits over traditional comment systems:

1. Ownership: You keep your content on your own domain
2. Decentralization: No single platform controls the conversation
3. Privacy: No third-party tracking by default
4. Standards-based: Built on open web standards

Quick Start

To get started with Webmentions, you need to:

1. Choose Your Approach

There are three main approaches to implementing Webmentions:

2. Set Up Receiving

To receive Webmentions, you need an endpoint. The simplest way is to use a hosted service:

Using Webmentions.com (Recommended)

<!-- Add this to your HTML <head> -->
<link rel="webmention" href="https://receive.webmentions.com/yourdomain.com" />

<!-- Optional: Also receive legacy pingbacks -->
<link rel="pingback" href="https://receive.webmentions.com/xmlrpc/yourdomain.com" />

Our hosted service handles receiving, verifying, and storing your Webmentions automatically. Replace yourdomain.com with your actual domain.

The optional pingback endpoint captures mentions from older WordPress sites and blogs that haven't migrated to Webmentions yet. Both appear in your dashboard as unified mentions.

Self-Hosted Endpoint

If you prefer to host your own endpoint:

// Example Express.js endpoint
app.post('/webmention', async (req, res) => {
  const { source, target } = req.body;

  // Validate
  if (!source || !target) {
    return res.status(400).send('Missing source or target');
  }

  // Queue for verification
  await verifyAndStore(source, target);

  res.status(202).send('Accepted');
});

3. Display Received Mentions

Once you're receiving Webmentions, you'll want to display them:

// Fetch mentions for a specific page
const mentions = await fetch(
  'https://api.webmentions.com/mentions?target=https://yoursite.com/post'
);

const data = await mentions.json();

// Display each mention
data.mentions.forEach(mention => {
  console.log(`${mention.author.name} mentioned your post`);
});

4. Send Webmentions

To notify others when you mention them:

Manual Sending

Use Webmentions.com to manually send Webmentions through our dashboard, or try Telegraph as an alternative.

Automatic Sending

Integrate Webmention sending into your publishing workflow:

async function sendWebmention(source, target) {
  // Discover endpoint
  const endpoint = await discoverEndpoint(target);

  if (!endpoint) return;

  // Send mention
  await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ source, target })
  });
}

Next Steps

Now that you understand the basics:

1. Learn about Microformats - Enhance your mentions with semantic markup
2. Implement Verification - Ensure mentions are legitimate
3. Handle Security - Protect against spam and abuse

Common Use Cases

Blog Comments

Replace traditional comments with Webmentions to let readers respond from their own sites.

Social Interactions

Use Webmentions to collect likes, shares, and bookmarks from across the web.

Event RSVPs

Accept event responses via Webmentions instead of requiring account creation.

Cross-Site Conversations

Enable threaded discussions that span multiple domains.

Resources

• Webmention Specification
• IndieWeb Wiki
• Webmention.rocks - Test suite
• Community Chat

Troubleshooting

Mentions Not Appearing?

1. Check your endpoint is correctly configured
2. Verify the source actually links to your target URL
3. Look for errors in your endpoint logs
4. Test with webmention.rocks

Receiving Spam?

Implement these protections:

• Require manual moderation for first-time domains
• Use allowlists for trusted sources
• Implement rate limiting
• Verify backlinks exist before displaying

Get Help

If you run into issues:

• Check the FAQ section
• Join the IndieWeb chat
• Review the specification
• Search existing implementation examples

Welcome to the Webmention community!