feat: destination metadata & delivery_metadata

[alexluong]

implements #534 & #537

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
outpost-docs	Ready	Preview	Comment	Oct 21, 2025 3:30am
outpost-website	Ready	Preview	Comment	Oct 21, 2025 3:30am

💡 Enable Vercel Agent with $100 free credit for automated AI reviews

[leggetter]

@claude - should we cover the changes in this PR anywhere within ./docs?

[claude]

Claude finished @leggetter's task —— View job

---

Documentation Review Complete

• Review PR changes to understand new features
• Check existing documentation structure
• Provide documentation recommendation

---

Analysis

This PR adds two new fields to destinations:

1. delivery_metadata - Static key-value pairs that are automatically merged into event metadata on every delivery (encrypted, sensitive data like auth tokens)
2. metadata - Arbitrary contextual information stored with the destination (not encrypted, for organizational purposes)

Key Implementation Details

From the code review:

• delivery_metadata is merged during event delivery with priority: system metadata < delivery_metadata < event.Metadata (internal/destregistry/basepublisher.go:68-95)
• delivery_metadata is encrypted in Redis (similar to credentials) because it may contain sensitive data
• metadata is stored unencrypted and is purely for contextual/organizational purposes
• Both fields are added to all destination types (webhook, SQS, RabbitMQ, Hookdeck, Kinesis, Azure Service Bus, GCP Pub/Sub, S3)
• OpenAPI spec has been updated with comprehensive documentation

Recommendation

Yes, this should be documented in ./docs. Here's what needs updating:

1. docs/pages/references/api.mdx (Lines 116-134)

The Destination Object example needs updating to include the new fields:

{
  "id": "des_12345",
  "type": "webhooks",
  "topics": ["user.created", "user.updated"],
  "config": { "url": "https://example.com/webhooks/user" },
  "credentials": { "secret": "some***********" },
  "delivery_metadata": { "app-id": "my-app", "region": "us-east-1" },  // NEW
  "metadata": { "team": "platform", "owner": "engineering" },           // NEW
  "disabled_at": null,
  "created_at": "2024-01-01T00:00:00Z"
}

Add explanatory text after the Destination Object (around line 136):

• delivery_metadata (optional): Static key-value pairs automatically merged into event metadata on every delivery. Encrypted like credentials. Useful for adding context like app identifiers, regions, or auth tokens that should be included with all events from this destination.
• metadata (optional): Arbitrary contextual information stored with the destination for organizational purposes (e.g., team ownership, cost center). Not included in event deliveries.

2. docs/pages/features/destinations.mdx (Around line 42)

Update the example curl command to show the optional fields:

curl --location 'localhost:3333/api/v1/<TENANT_ID>/destinations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
 "type": "<TYPE>",
 "topics": ["<TOPIC>"],
 "config": {
    "url": "https://example.test/webhooks"
 },
 "delivery_metadata": {
    "app-id": "my-app"
 }
}'

3. docs/pages/features/publish-events.mdx (Around line 37-38)

Update the explanation of metadata merging to mention delivery_metadata:

The metadata field in published events is merged with the destination's delivery_metadata before being translated to the destination's native format. The merge priority is: system metadata (event-id, topic, timestamp) < destination's delivery_metadata < event metadata. This means event metadata has the highest priority and can override delivery_metadata values.

Summary

These new fields provide important functionality:

• delivery_metadata: Enables static metadata injection at the destination level (useful for multi-region, multi-app scenarios)
• metadata: Enables better destination organization and management

Both warrant documentation as they're user-facing API features that change how destinations are configured and how events are delivered.

---

Job Run | Branch: destination-metadata

[alexluong]

there's some issue with destwebhookstandard, will fix in the v0.8.0 branch

[leggetter]

@alexluong - should/do we have an issue to support adding something related to this to the Portal UI?

[alexluong]

@leggetter great question, for delivery_metadata, I do think so. Let me ping Thomas on Slack. Let's keep the original issue opened until the portal is fully suppoted?