Import an existing signing secret when creating an outbound endpoint

README.md

@@ -227,6 +227,8 @@ const endpoint = await relay.outbound.endpoints.create("customer_42", {
   eventTypes: ["invoice.paid"],
 });
 // endpoint.secret is the signing secret your customer verifies deliveries with.
+// Migrating from Svix or another Standard Webhooks sender? Pass `secret` with the
+// endpoint's existing whsec_ secret so your customer keeps verifying with it.
 
 // Every time the event happens.
 const message = await relay.outbound.messages.publish(

src/resources/outbound.ts

@@ -7,6 +7,7 @@ import type {
   OutboundConsumer,
   OutboundDelivery,
   OutboundEndpoint,
+  OutboundEndpointCreateParams,
   OutboundEndpointParams,
   OutboundEndpointWithSecret,
   OutboundEventType,
@@ -140,7 +141,8 @@ export class OutboundEndpointsResource {
 
   /**
    * Register an HTTPS endpoint for a consumer. The result carries the signing
-   * secret your customer verifies deliveries with.
+   * secret your customer verifies deliveries with: a new one, or `secret` when
+   * importing an existing Standard Webhooks secret (e.g. from Svix).
    *
    * ```ts
    * const endpoint = await relay.outbound.endpoints.create("customer_42", {
@@ -149,7 +151,7 @@ export class OutboundEndpointsResource {
    * });
    * ```
    */
-  create(consumerId: string, params: OutboundEndpointParams): Promise<OutboundEndpointWithSecret> {
+  create(consumerId: string, params: OutboundEndpointCreateParams): Promise<OutboundEndpointWithSecret> {
     return this.http.unwrap(
       this.http.api.v1.outboundConsumersEndpointsCreate(
         segment(consumerId),

src/types.ts

@@ -562,6 +562,16 @@ export interface OutboundEndpointParams {
   functionId?: string;
 }
 
+/** Endpoint configuration for `endpoints.create`, with an optional secret to import. */
+export interface OutboundEndpointCreateParams extends OutboundEndpointParams {
+  /**
+   * Existing Standard Webhooks signing secret to import (`whsec_` + base64 of a
+   * 24-64 byte key, e.g. exported from Svix) so the consumer keeps verifying
+   * with the key it already has. Omit it to generate a new secret.
+   */
+  secret?: string;
+}
+
 export interface PublishOutboundMessageParams {
   consumer: string;
   event_type?: string;

test/outbound.test.ts

@@ -50,6 +50,20 @@ describe("outbound", () => {
     expect(calls[1]?.body).toEqual({ url: "https://example.com/v2", event_types: ["a"] });
   });
 
+  it("imports an existing signing secret on create", async () => {
+    const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";
+    const { relay, calls } = createClient(() => ({ json: { id: "endpoint-1", secret } }));
+
+    const endpoint = await relay.outbound.endpoints.create("customer_42", {
+      url: "https://example.com/hook",
+      eventTypes: ["invoice.paid"],
+      secret,
+    });
+
+    expect(endpoint.secret).toBe(secret);
+    expect(calls[0]?.body).toEqual({ url: "https://example.com/hook", event_types: ["invoice.paid"], secret });
+  });
+
   it("pauses, resumes and handles signing secrets", async () => {
     const { relay, calls } = createClient((url) =>
       url.includes("/secret/") ? { json: { secret: "whsec_new" } } : { json: { id: "endpoint-1", state: "paused" } },